|
| 1 | +--- |
| 2 | +applyTo: "**" |
| 3 | +--- |
| 4 | + |
| 5 | +# Repository conventions |
| 6 | + |
| 7 | +## Purpose |
| 8 | + |
| 9 | +Canonical rule source for cross-cutting NovaModuleTools conventions that apply to every change. Topic-specific rules live in the other `.instructions.md` files; this file owns the rules that do not belong to one topic. |
| 10 | + |
| 11 | +## Project layering |
| 12 | + |
| 13 | +- Treat `project.json` as the source of truth for project metadata, build output, package settings, and release settings. |
| 14 | +- Treat `project.json` `Manifest.PowerShellHostVersion` as the compatibility target for PowerShell code, tests, and examples. If a project targets `5.1`, do not introduce PowerShell 7.x-only syntax, cmdlets, parameters, or APIs unless the work explicitly adds guarded compatibility handling. |
| 15 | +- Use Nova commands and repository wrappers for build, test, package, and release workflows; do not replace them with ad hoc PowerShell module build scripts. |
| 16 | +- Do not create or maintain hand-written module `.psm1` or module `.psd1` files in source; Nova generates the built module root and manifest under `dist/NovaModuleTools/` from `project.json` and `src/**/*.ps1`. |
| 17 | +- Preserve the distinction between PowerShell cmdlet UX and `nova` CLI UX. |
| 18 | + |
| 19 | +## File ownership |
| 20 | + |
| 21 | +- `src/public/` files own exactly one top-level function each. The file name matches the function name. |
| 22 | +- `src/private/` files expose at most one externally called function per file. Additional helpers may stay as sibling top-level functions in the same file when they belong to that entry function. The file name matches the externally called function. |
| 23 | +- PowerShell functions must not declare nested functions inside their bodies. |
| 24 | +- Prefer existing helpers and support files over ad hoc duplication. |
| 25 | +- Do not add raw infrastructure calls in public commands when an adapter/helper layer already exists. |
| 26 | + |
| 27 | +## Validation expectations |
| 28 | + |
| 29 | +Use the smallest validation set that proves the change, then run the repository quality loop before finishing code work: |
| 30 | + |
| 31 | +- local quality loop: `pwsh -NoLogo -NoProfile -File ./run.ps1` |
| 32 | +- test validation: `Test-NovaBuild` |
| 33 | +- analyzer only: `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` |
| 34 | +- CI-parity coverage flow: `./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1 -OutputDirectory ./artifacts` |
| 35 | + |
| 36 | +If `run.ps1` or `./scripts/build/Invoke-ScriptAnalyzerCI.ps1` reports findings, fix them before review, handoff, or commit. Do not treat a failing local quality loop as an acceptable stopping point. |
| 37 | + |
| 38 | +When CodeScene tooling is available: |
| 39 | + |
| 40 | +- run the pre-commit safeguard on AI-touched changes before suggesting a commit |
| 41 | +- run a branch/change-set analysis before suggesting a PR or declaring a larger change ready |
| 42 | +- if CodeScene reports a regression, refactor instead of treating the work as done |
| 43 | + |
| 44 | +If CodeScene tooling is unavailable locally, continue with the normal repository validation flow; pull requests and CI remain the effective gate. |
| 45 | + |
| 46 | +For documentation-only changes, executable validation may be skipped if no code path or workflow behavior changed. |
| 47 | + |
| 48 | +## Documentation review |
| 49 | + |
| 50 | +- Review `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` after every meaningful change. |
| 51 | +- Update tests when behavior changes. |
| 52 | + |
| 53 | +## File formatting rule |
| 54 | + |
| 55 | +- Before handoff, review every changed or created text file and ensure it ends with exactly one trailing newline and no extra blank lines at the bottom. |
| 56 | +- Do not leave any edited file with extra blank lines at the end, even if the functional code change is already complete. |
| 57 | +- Do not alter internal whitespace just to enforce the trailing newline rule. |
| 58 | + |
| 59 | +## Safety constraints |
| 60 | + |
| 61 | +- Do not publish packages, create tags, or push changes unless explicitly requested. |
| 62 | +- Do not modify GitHub Actions release automation casually; `Publish.yml` mutates `main` and `develop`. |
| 63 | +- Do not bypass warnings or guards silently; Nova uses explicit `-OverrideWarning` / `--override-warning`. |
| 64 | + |
| 65 | +## Commit message guidance |
| 66 | + |
| 67 | +- When you are asked to suggest or prepare a commit message, answer in English. |
| 68 | +- Use Conventional Commit format. |
| 69 | +- Extract the ticket number from `$GIT_BRANCH_NAME` and render it as `(#<number>)` immediately after the type when one is available. |
| 70 | +- If `$GIT_BRANCH_NAME` starts with `hotfix/` or `bug/`, use `fix` as the type even when the implementation looks more like a feature. Use `fix!` if that branch change is also breaking. |
| 71 | +- Otherwise estimate the type from the actual change: |
| 72 | + - `feat` for feature work |
| 73 | + - `fix` for bug fixes |
| 74 | + - `feat!` for breaking feature work |
| 75 | + - `fix!` for breaking fixes |
| 76 | +- Keep the subject short, specific, and free of unnecessary detail. |
| 77 | +- If you provide multiple commit message suggestions or summarize multiple change options, use bullet points. |
| 78 | +- Do not invent a ticket number when `$GIT_BRANCH_NAME` does not contain one. |
| 79 | + |
| 80 | +## Markdown output |
| 81 | + |
| 82 | +When the output is intended to be copied as Markdown from the UI or written to a Markdown file, follow the `markdown-authoring` skill (`.github/skills/markdown-authoring/SKILL.md`). Apply that rule especially to release summaries, review summaries, contributor-facing Markdown docs, prompt output, and PR-template-shaped text. |
0 commit comments