Skip to content

Use GitHub milestones and labels for tracking implementation phases #48

@michaeldistel

Description

@michaeldistel

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions