Improve setup instructions and documentation consistency - #21
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR enhances the project template with improved documentation, refactored command-line handling, and better project configuration. The changes focus on making the template more maintainable and easier to use for new projects.
Changes:
- Refactored command-line parsing in Console and CodeGen projects from async factory pattern to constructor-based initialization
- Reorganized project configurations for AOT compatibility settings and documentation generation
- Enhanced README with clearer setup instructions, detailed usage examples, and improved formatting
- Added build dependency for Console project in solution file
- Created separate classes for API integration (ApiNinjas) and code generation (CodeGenBuilder) in CodeGen project
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Comprehensive documentation improvements including clearer setup instructions, expanded usage examples, and restructured template setup guide |
| Tests/Tests.csproj | Added blank line for consistent formatting |
| ProjectTemplate.slnx | Added build dependency for Console project on Library |
| ProjectTemplate.code-workspace | Added spell check dictionary entries for new terms |
| Library/Library.csproj | Reorganized properties, moved documentation settings to .editorconfig |
| Library/.editorconfig | Added local configuration to suppress CS1591 XML comment warnings |
| Console/Program.cs | Refactored to use constructor-based CommandLine initialization, added ExecuteTestAsync method |
| Console/Console.csproj | Reorganized AOT settings, added InformationalVersion property |
| Console/CommandLine.cs | Changed from async factory pattern to constructor initialization, renamed Context to Options, added test command support |
| CodeGen/Program.cs | Refactored to use constructor-based initialization, extracted API and code generation logic to separate classes |
| CodeGen/CommandLine.cs | Changed from async factory pattern to constructor initialization, renamed Context to Options |
| CodeGen/CodeGen.csproj | Reorganized AOT settings similar to Console project |
| CodeGen/CodeGenBuilder.cs | New file extracting code generation logic from Program.cs |
| CodeGen/ApiNinjas.cs | New file extracting API Ninjas integration from Program.cs |
| Benchmarks/Benchmarks.csproj | Reordered IsPackable property for consistency |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
ptr727
added a commit
that referenced
this pull request
Jul 17, 2026
Fixes #332 (core gap + the six bundled nits from the #330 sweep reviews; two of the six live in the blessed downstream reference and propagate via the Vantage-Config carry, not this repo - see below). ## configure.sh: model inference on downstream carries In a carry the registry is absent, so the no-arg form defaulted to `release` and then hit the intended fail-safe abort on operational carries (missing `develop.json`) - arg 2 was effectively mandatory there. Now the model is inferred from which `develop` payload is carried (a carry holds exactly its own model's); ambiguous layouts (both or neither - e.g. a partial copy) abort rather than guess. Also: the model may be passed as the sole argument (`configure.sh operational`) - previously arg 1 was always parsed as a repo name (bundled nit, Utilities #417). Matrix-tested with the apply path stubbed: infer release, infer operational, both-present abort (exit 1), neither-present abort (exit 1), explicit arg-2 override, model-as-sole-arg, unknown-model abort. Hub behavior unchanged (registry present -> registry lookup, as before). shellcheck + bash -n clean. ## Ruleset snippet hardening (duplicate-name id corruption) The `id=$(gh api ... select(.name==...).id)` pattern in the README regen snippet and AUDIT.md section 6 produced a **multiline id** when duplicate same-name rulesets exist, silently corrupting the follow-up API path (bundled nit, Utilities #417 + LanguageTags #278). Both snippets now fetch the list once and enforce **exactly one** ruleset per name: the regen snippet fails loudly (never regen from a guess); the audit snippet reports `found N (defect/drift)` and continues - matching the declared drift semantics. Live-tested read-only against this repo (develop + main in sync; duplicate simulation counts correctly). ## README wording Documents the inference fallback and the model-only argument form (bundled nit, Utilities #417). ## Bundled nits NOT in this PR (with rationale) - `gh api --input -` portability (MediaTools #19): declined - fleet standard is current gh; not worth temp-file churn. - jq-derived secret name lists + `--paginate` in the secrets check (MediaTools #19, LanguageTags #278, PlexCleaner #854): these live in the **blessed downstream self-audit reference** (the Vantage-Config carry), not in hub files - propagated there directly after this merges (the hub's fleet audit reads `spec/secrets.json` programmatically already). ## Propagation caveat This re-drifts the five existing carries (Vantage-Config + the four #330 sweep repos) until their next conformance touch; Vantage-Config is updated immediately after this merges since it is the blessed reference the queued operational standups (HomeAssistant-Config #16, ESPHome-Config #46, HomeAutomation-Config #21) will adapt from. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 17, 2026
Closed
ptr727
added a commit
that referenced
this pull request
Jul 17, 2026
Reconciles the HomeAutomation-Config registry entry after the #21 conformance carry landed on its develop (54637c4, 2026-07-16) - same close-out pattern as #329 did for Vantage-Config. - "Operational rollout pending" was stale: lint CI (test-pull-request.yml feeding the required check), the dispatch-only publisher (publish-release.yml + version.json), and develop-as-ground-truth were already live; the carry added the repo-config operational baseline (rulesets/settings verified in sync via the carried self-audit), the adapted AUDIT.md + spec/secrets.json, and the Dependabot merge-bot. - The "strip the legacy Vantage/ subtree" instruction is updated to record it as done (verified: no such tree on develop). - The outstanding owner task (App secret pair in both stores; merge-bot inert until then) is recorded so the entry reflects reality. `spec/validate.py` passes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 17, 2026
ptr727
added a commit
that referenced
this pull request
Jul 17, 2026
…337) Fixes #336: the branch-drift check derived "main carries content develop lacks" from the three-dot compare alone, which lists files changed on main since the merge-base and is blind to cherry-picked (patch-equivalent) promotions. Any repo promoting via cherry-pick branches re-triggered the finding on every audit - HomeAutomation-Config #21's forward-sync task was authored and worked against exactly this false positive. ## Fix Post-filter the compare's `files[]` by **blob equality at the two heads** (one `git/trees?recursive=1` call per head, as the issue suggested): a path whose blob SHA matches at `develop` and `main` is content develop already has, not content it lacks. Only the remainder raises the DRIFT finding. - The finding now **names the lacking files** (up to 8) - addressing the issue's impact note that "N+ changed file(s)" gave a downstream reader nothing to spot-check. - If either tree comes back `truncated` (very large repos), the filter is skipped and the unfiltered finding is kept, marked "tree too large to blob-filter cherry-pick noise" - conservative, never silently suppressing. - Deletions on main still flag (path absent from main's blobs but present on develop's is a blob mismatch), as do renames. ## Verification (live, read-only) - **False positive resolved**: `python3 spec/audit.py HomeAutomation-Config` -> clean (previously: `DRIFT branch: main carries 2+ changed file(s)...` from the cherry-picked cspell-scope promotions; both files are blob-identical at the heads). - **Genuine positives still fire, now with names**: homeassistant-purpleair -> `main carries 2 file(s) develop lacks: requirements-test.txt, requirements.txt`; DevKitCIoT -> `main carries 12 file(s) develop lacks: .editorconfig, ...` (first 8 shown). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Enhance the README for clearer setup instructions and update branding for consistency. Adjust merge rules and clarify requirements in the documentation. Include additional project files and configurations to support development and code generation tasks.