Skip to content

Commit 974e96a

Browse files
DKFuHDKFuH
committed
docs: add v0.4.0 roadmap, issue drafts, and GitHub setup notes
1 parent 0e95e0d commit 974e96a

File tree

10 files changed

+351
-12
lines changed

10 files changed

+351
-12
lines changed

‎README.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,8 +117,11 @@ See the full example in [`examples/craft-business-lead-to-order.orgs`](examples/
117117
- [`docs/ast-v0.2.md`](docs/ast-v0.2.md)
118118
- [`docs/cli-v0.1-plan.md`](docs/cli-v0.1-plan.md)
119119
- [`docs/language-principles.md`](docs/language-principles.md)
120+
- [`docs/github-labels.md`](docs/github-labels.md)
121+
- [`docs/github-project-setup.md`](docs/github-project-setup.md)
120122
- [`docs/orgscript-for-humans.md`](docs/orgscript-for-humans.md)
121123
- [`docs/orgscript-for-ai.md`](docs/orgscript-for-ai.md)
124+
- [`docs/roadmaps/v0.4.0.md`](docs/roadmaps/v0.4.0.md)
122125
- [`docs/repository-structure.md`](docs/repository-structure.md)
123126
- [`docs/syntax.md`](docs/syntax.md)
124127
- [`docs/semantics.md`](docs/semantics.md)
@@ -171,11 +174,13 @@ Exit codes are CI-friendly:
171174

172175
## Near-term plan
173176

174-
1. Build a parser that validates `.orgs` files.
175-
2. Emit a canonical AST for downstream tooling.
176-
3. Add a formatter for deterministic file layout.
177-
4. Add a linter for operational modeling mistakes.
178-
5. Expand the examples with real-world business cases.
177+
1. Add `format --check` for CI and pre-commit workflows.
178+
2. Show real JSON diagnostics examples in the README and diagnostics spec.
179+
3. Add `orgscript check` as a combined quality command.
180+
4. Improve diagnostics consistency across CLI commands.
181+
5. Add an initial VS Code syntax highlighting scaffold.
182+
183+
See [`docs/roadmaps/v0.4.0.md`](docs/roadmaps/v0.4.0.md) for the current milestone plan.
179184

180185
## CLI
181186

‎ROADMAP.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,15 +29,18 @@
2929
- Generate diagrams and documentation from the model
3030
- Add localization architecture for keyword packs
3131

32+
## v0.4
33+
34+
- Add `format --check` for CI and pre-commit workflows
35+
- Document real JSON diagnostics examples in README and diagnostics spec
36+
- Add `orgscript check` as a combined quality command
37+
- Improve consistency of human-readable CLI diagnostics
38+
- Add an initial VS Code syntax highlighting scaffold
39+
3240
## Unreleased
3341

34-
- Add first AST-backed formatter command
35-
- Enforce formatter stability through parser/formatter roundtrip tests
36-
- Add first AST-backed linter command
37-
- Add lint fixtures for suspicious but syntactically valid models
38-
- Formalize lint severities and stable lint output ordering
39-
- Add machine-readable diagnostics for validate and lint
40-
- Add CI workflows for tests, validation, and example linting
42+
- Open the v0.4.0 developer-experience milestone
43+
- Prepare issue drafts for formatter checks, diagnostics docs, combined quality checks, diagnostics consistency, and editor support
4144

4245
## Later
4346

‎docs/github-labels.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# GitHub Labels
2+
3+
These labels provide a small, stable vocabulary for OrgScript issue triage and milestone planning.
4+
5+
## Release labels
6+
7+
- `v0.4.0`
8+
- work explicitly planned for the v0.4.0 milestone
9+
10+
## Focus labels
11+
12+
- `dx`
13+
- developer experience and contributor ergonomics
14+
- `cli`
15+
- command-line behavior, flags, and output
16+
- `formatter`
17+
- canonical formatting behavior
18+
- `diagnostics`
19+
- human-readable and machine-readable diagnostics
20+
- `editor`
21+
- editor support such as syntax highlighting or extension scaffolds
22+
- `documentation`
23+
- README, guides, examples, or reference docs
24+
- `quality`
25+
- combined checks, CI paths, or release-hardening work
26+
27+
## Contribution labels
28+
29+
- `good first issue`
30+
- approachable tasks for first-time contributors
31+
- `help wanted`
32+
- tasks where outside help is actively welcome
33+
34+
## Suggested usage
35+
36+
- use one release label when a task belongs to a milestone
37+
- combine one or two focus labels to describe the work area
38+
- add contribution labels only when an issue is genuinely well-scoped for outside contributors

‎docs/github-project-setup.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# GitHub Project Setup
2+
3+
This document turns the local v0.4.0 planning artifacts into a clean GitHub milestone and issue set.
4+
5+
## Milestone
6+
7+
- name: `v0.4.0`
8+
- title suggestion: `v0.4.0 - Developer Experience`
9+
- goal: make OrgScript easier to use in local workflows, CI, and editors without expanding the language surface
10+
11+
## Issue creation order
12+
13+
1. [`feat(format): add --check mode for canonical formatting`](issues/v0.4.0/01-format-check.md)
14+
2. [`docs(cli): add JSON diagnostics examples and contract`](issues/v0.4.0/02-json-diagnostics-docs.md)
15+
3. [`feat(cli): add orgscript check as a combined quality command`](issues/v0.4.0/03-check-command.md)
16+
4. [`enhancement(diagnostics): make CLI output more consistent and machine-friendly`](issues/v0.4.0/04-diagnostics-consistency.md)
17+
5. [`feat(editor): add initial VS Code syntax highlighting scaffold`](issues/v0.4.0/05-vscode-syntax-highlighting.md)
18+
19+
## Suggested labels
20+
21+
- `v0.4.0`
22+
- `dx`
23+
- `cli`
24+
- `formatter`
25+
- `diagnostics`
26+
- `editor`
27+
- `documentation`
28+
- `quality`
29+
- `good first issue`
30+
- `help wanted`
31+
32+
## Suggested release flow
33+
34+
1. create the `v0.4.0` milestone
35+
2. create the five milestone issues from the local drafts
36+
3. apply release and focus labels consistently
37+
4. start implementation in the recommended order
38+
5. when milestone scope is complete, prepare release notes under `docs/releases/`
39+
6. wait for `main` CI to be green before tagging
40+
41+
## Notes
42+
43+
- Keep GitHub issue titles identical to the local draft titles.
44+
- Prefer linking milestone issues back to the roadmap when relevant.
45+
- Do not widen the milestone with new language features unless a concrete adoption blocker appears.

‎docs/issues/v0.4.0/01-format-check.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# feat(format): add --check mode for canonical formatting
2+
3+
## Why
4+
5+
`orgscript format` can already normalize files, but CI and pre-commit workflows also need a non-mutating check mode.
6+
7+
## Scope
8+
9+
- add `orgscript format <file> --check`
10+
- exit `0` when the file is already canonically formatted
11+
- exit `1` when formatting changes would be required
12+
- keep current write-in-place behavior unchanged when `--check` is not used
13+
- produce clear output that explains whether the file is canonical
14+
15+
## Definition Of Done
16+
17+
- CLI supports `--check`
18+
- tests cover:
19+
- already formatted file
20+
- non-canonical file
21+
- invalid file
22+
- README contains one short `format --check` example
23+
- CI can use `format --check` without modifying files
24+
25+
## Labels
26+
27+
- `v0.4.0`
28+
- `enhancement`
29+
- `dx`
30+
- `cli`
31+
- `formatter`
32+
33+
## Dependencies
34+
35+
- none
36+
37+
## Notes
38+
39+
Prefer deterministic messages so the command works well in local shells, CI logs, and future editor integrations.

‎docs/issues/v0.4.0/02-json-diagnostics-docs.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# docs(cli): add JSON diagnostics examples and contract
2+
3+
## Why
4+
5+
The machine-readable diagnostics are one of OrgScript's strongest integration points, but they are not yet visible enough in the public docs.
6+
7+
## Scope
8+
9+
- document `orgscript validate <file> --json` in the README
10+
- document `orgscript lint <file> --json` in the README
11+
- add concrete JSON output examples for valid and invalid cases
12+
- clarify severity fields, file and line structure, and exit behavior
13+
- keep the examples aligned with real CLI output
14+
15+
## Definition Of Done
16+
17+
- README contains at least one real JSON example for `validate --json`
18+
- README contains at least one real JSON example for `lint --json`
19+
- [`spec/diagnostics.md`](../../../spec/diagnostics.md) stays consistent with the examples
20+
- examples are derived from current fixtures or golden-style snapshots
21+
22+
## Labels
23+
24+
- `v0.4.0`
25+
- `documentation`
26+
- `dx`
27+
- `cli`
28+
- `diagnostics`
29+
30+
## Dependencies
31+
32+
- none
33+
34+
## Notes
35+
36+
This issue is deliberately documentation-first. It should not introduce new diagnostics behavior unless the docs uncover a mismatch.

‎docs/issues/v0.4.0/03-check-command.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# feat(cli): add orgscript check as a combined quality command
2+
3+
## Why
4+
5+
Most contributors want one command that answers the practical question: "Is this file ready?" A combined quality command reduces friction and makes OrgScript easier to adopt in CI and local workflows.
6+
7+
## Scope
8+
9+
- add `orgscript check <file>`
10+
- run `validate`, `lint`, and `format --check` in one command
11+
- produce a single summary that explains which sub-checks passed or failed
12+
- keep exit behavior CI-friendly
13+
14+
## Definition Of Done
15+
16+
- CLI exposes `orgscript check <file>`
17+
- success and failure paths are covered by tests
18+
- output clearly identifies failing sub-checks
19+
- README contains one example
20+
- command works well as a single entry point for local verification
21+
22+
## Labels
23+
24+
- `v0.4.0`
25+
- `enhancement`
26+
- `dx`
27+
- `cli`
28+
- `quality`
29+
30+
## Dependencies
31+
32+
- [`feat(format): add --check mode for canonical formatting`](01-format-check.md)
33+
34+
## Notes
35+
36+
Prefer composition over duplication. `check` should reuse the existing command logic rather than reimplementing validation behavior.

‎docs/issues/v0.4.0/04-diagnostics-consistency.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# enhancement(diagnostics): make CLI output more consistent and machine-friendly
2+
3+
## Why
4+
5+
OrgScript now has multiple quality commands. Their human-readable output should feel intentionally designed, not merely functional.
6+
7+
## Scope
8+
9+
- standardize text output shape across `validate`, `lint`, and `format --check`
10+
- keep severity, code, file, line, and message ordering stable
11+
- align JSON and text diagnostics so they describe the same result consistently
12+
- improve wording for a handful of common error and finding messages
13+
14+
## Definition Of Done
15+
16+
- CLI output is visibly consistent across representative commands
17+
- tests assert both output content and output structure
18+
- at least five common error or finding messages are improved
19+
- JSON diagnostics remain stable while text output becomes easier to scan
20+
21+
## Labels
22+
23+
- `v0.4.0`
24+
- `enhancement`
25+
- `dx`
26+
- `diagnostics`
27+
- `ux`
28+
29+
## Dependencies
30+
31+
- [`feat(format): add --check mode for canonical formatting`](01-format-check.md)
32+
- [`feat(cli): add orgscript check as a combined quality command`](03-check-command.md)
33+
34+
## Notes
35+
36+
This is about consistency, not verbosity. Prefer small, stable output contracts over highly decorative CLI output.

‎docs/issues/v0.4.0/05-vscode-syntax-highlighting.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# feat(editor): add initial VS Code syntax highlighting scaffold
2+
3+
## Why
4+
5+
A language project becomes much easier to adopt once files are readable in a mainstream editor. Syntax highlighting is a high-leverage DX improvement without changing the language itself.
6+
7+
## Scope
8+
9+
- add a minimal VS Code extension scaffold for `.orgs`
10+
- register the `.orgs` extension
11+
- highlight:
12+
- top-level blocks
13+
- core keywords
14+
- strings
15+
- operators
16+
- document local installation and usage
17+
18+
## Definition Of Done
19+
20+
- `.orgs` files are recognized by VS Code
21+
- OrgScript keywords receive basic syntax highlighting
22+
- extension scaffold lives in the repository with a short setup guide
23+
- README or docs mention the editor integration
24+
25+
## Labels
26+
27+
- `v0.4.0`
28+
- `enhancement`
29+
- `dx`
30+
- `editor`
31+
32+
## Dependencies
33+
34+
- none
35+
36+
## Notes
37+
38+
Keep the first pass small and explicit. A basic TextMate grammar is enough for the initial milestone.

‎docs/roadmaps/v0.4.0.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# v0.4.0 Roadmap
2+
3+
Milestone title: `v0.4.0 - Developer Experience`
4+
5+
## Goal
6+
7+
Make OrgScript easier to use in daily development, CI, and editor workflows without expanding the language surface.
8+
9+
## Release focus
10+
11+
- CLI ergonomics
12+
- better documentation for machine-readable output
13+
- editor support foundation
14+
- stable quality workflows for contributors
15+
16+
## Non-goals
17+
18+
- new language keywords
19+
- localization
20+
- larger parser refactors
21+
- new semantic block types
22+
- SaaS or hosted tooling
23+
24+
## Planned issues
25+
26+
1. [`feat(format): add --check mode for canonical formatting`](../issues/v0.4.0/01-format-check.md)
27+
2. [`docs(cli): add JSON diagnostics examples and contract`](../issues/v0.4.0/02-json-diagnostics-docs.md)
28+
3. [`feat(cli): add orgscript check as a combined quality command`](../issues/v0.4.0/03-check-command.md)
29+
4. [`enhancement(diagnostics): make CLI output more consistent and machine-friendly`](../issues/v0.4.0/04-diagnostics-consistency.md)
30+
5. [`feat(editor): add initial VS Code syntax highlighting scaffold`](../issues/v0.4.0/05-vscode-syntax-highlighting.md)
31+
32+
## Recommended order
33+
34+
1. `format --check`
35+
2. JSON diagnostics examples and contract sync
36+
3. `orgscript check`
37+
4. diagnostics consistency improvements
38+
5. VS Code syntax highlighting scaffold
39+
40+
## Why this order
41+
42+
- `format --check` unlocks CI and pre-commit flows immediately.
43+
- JSON diagnostics examples make current machine-facing features visible and reusable.
44+
- `orgscript check` becomes much more useful once formatting and diagnostics are stable.
45+
- diagnostics consistency should build on the exact commands users will run.
46+
- editor support is a strong DX improvement, but it depends less on the CLI path.
47+
48+
## Success criteria
49+
50+
- CI can verify canonical formatting without rewriting files.
51+
- README shows real JSON examples for `validate --json` and `lint --json`.
52+
- Contributors have one clear quality command for routine checks.
53+
- CLI output feels predictable in both text and JSON modes.
54+
- `.orgs` files are easier to read in a mainstream editor.
55+
56+
## After v0.4.0
57+
58+
The next phase should focus on visible integrations and real-world validation:
59+
60+
- OrgScript to Mermaid
61+
- OrgScript to Markdown or HTML summaries
62+
- more domain-diverse example files
63+
- GitHub issue curation and external communication

0 commit comments

Comments
 (0)