Summary
Replace inline phase references in docs and README with GitHub milestones, and adopt a consistent label set for issues and PRs.
Problem with the current approach
Phase status is currently tracked as prose in README.md and CLAUDE.md. This creates several problems:
- It goes stale. A phase can be marked "pending" in the README while the work is already merged and done, or vice versa. Keeping it accurate requires a manual doc update on every PR.
- It is disconnected from actual work. There is no link between the phase description in the README and the issues or PRs that implement it. A reader cannot click through to see what was done, what is in progress, or what is left.
- It gives a false sense of granularity. Marking a whole phase as "completed" hides the fact that individual pieces may still have open bugs or missing edge cases tracked as separate issues.
- It does not help contributors. Someone wanting to contribute to Phase 6 has no way to find the relevant issues without manually searching.
Why milestones fix this
GitHub milestones are designed exactly for this. Each milestone shows a live progress bar (open vs closed issues), a due date if desired, and a list of every issue and PR attached to it. The README can link to a milestone URL instead of maintaining prose. When an issue is closed the milestone progress updates automatically with no doc change needed.
Milestones also make it easy to see at a glance what work remains in a phase, which helps both maintainers planning releases and contributors looking for work to pick up.
Why labels matter alongside milestones
Milestones answer "which phase does this belong to". Labels answer "what kind of thing is this". Together they allow fast filtering: "show me all bugs in Phase 6", "show me all good first issues across any phase". The current label set is the GitHub default and is missing types that are already showing up in this repo's issues (technical-debt, idea).
Suggested milestones
- Phase 0: C++ runtime (done)
- Phase 1: Lexer (done)
- Phase 2: Parser / AST (done)
- Phase 3: Semantic analysis (done)
- Phase 4: Functions (done)
- Phase 5: Function blocks / OOP (done)
- Phase 6: CODESYS compatibility (pending)
- Phase 7: OpenPLC integration (pending)
- Phase 8: Optimizations (pending)
- Phase 9: IEC testing framework (pending)
Suggested doc changes
- Replace "Phase N (pending/complete)" prose in
README.md and CLAUDE.md with links to the corresponding milestone
- Remove stale phase status text; let milestone progress reflect actual state
cc @thiagoralves
Summary
Replace inline phase references in docs and README with GitHub milestones, and adopt a consistent label set for issues and PRs.
Problem with the current approach
Phase status is currently tracked as prose in
README.mdandCLAUDE.md. This creates several problems:Why milestones fix this
GitHub milestones are designed exactly for this. Each milestone shows a live progress bar (open vs closed issues), a due date if desired, and a list of every issue and PR attached to it. The README can link to a milestone URL instead of maintaining prose. When an issue is closed the milestone progress updates automatically with no doc change needed.
Milestones also make it easy to see at a glance what work remains in a phase, which helps both maintainers planning releases and contributors looking for work to pick up.
Why labels matter alongside milestones
Milestones answer "which phase does this belong to". Labels answer "what kind of thing is this". Together they allow fast filtering: "show me all bugs in Phase 6", "show me all good first issues across any phase". The current label set is the GitHub default and is missing types that are already showing up in this repo's issues (
technical-debt,idea).Suggested milestones
Suggested doc changes
README.mdandCLAUDE.mdwith links to the corresponding milestonecc @thiagoralves