diff --git a/CHANGELOG.md b/CHANGELOG.md index 169e2fe4..52e71e17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ # considers commits from here forward. Hand-written history above this is left alone. last_commit_released: a1dfeaab1beb24b05d5443504b22c0dbf7f5edde name: GenPRES +# GenPRES stays alpha until the MVP work (auth, etc.) needed to replace the existing +# system is done. Without this, ShipIt would drop the -alpha suffix on the next +# fix/feat commit instead of doing a real version bump. +pre_release: alpha --- # Changelog @@ -136,7 +140,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- -## [0.1.2-alpha] - 2026-03-23 +## [0.1.2-alpha.1] - 2026-03-23 > ⚠️ **Alpha release** — Early development stage. Major features are incomplete. **Not for clinical use.** diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 21ec40ef..8bbb863d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -135,12 +135,14 @@ In the meantime, we can preview locally what it would generate: ```bash dotnet tool restore -dotnet shipit --dry-run --allow-branch master +dotnet shipit --dry-run --allow-branch master --skip-merge-commit ``` `--allow-branch` defaults to `main`; GenPRES's default branch is `master`, so it must be passed -explicitly (this also applies when step 5 wires ShipIt into CI). `--dry-run` never modifies files -or opens a pull request, so it's safe to run against a dirty tree. +explicitly (this also applies when step 5 wires ShipIt into CI). `--skip-merge-commit` is required +too: the repo's existing history has `Merge pull request ...` commits ShipIt can't parse, and it +throws on the first one it hits instead of skipping it. `--dry-run` never modifies files or opens +a pull request, so it's safe to run against a dirty tree. ### What Happens During `dotnet run` (the `Run` target) diff --git a/docs/implementation-plans/234-improve-build-system.md b/docs/implementation-plans/234-improve-build-system.md index 786a5247..ffb93680 100644 --- a/docs/implementation-plans/234-improve-build-system.md +++ b/docs/implementation-plans/234-improve-build-system.md @@ -15,9 +15,16 @@ explicitly requires an ADR before implementation. For versioning/changelog (items 1–2), three options were on the table: -- **MinVer / Nerdbank.GitVersioning** — tag-driven version at build time only. Low risk, but leaves changelog and release-PR creation unautomated (Repo Assist's Task 8 would keep doing that manually). -- **EasyBuild.ShipIt** — reads `CHANGELOG.md` front-matter and conventional-commit history, computes the next semver, generates the changelog section, and opens a release PR. Requires squash-merge so each PR maps to one commit. -- **Status quo** — keep the manual `Directory.Build.props` edit and Repo Assist's manual changelog PRs. Rejected: this is exactly what #234 was filed to fix. +- **MinVer / Nerdbank.GitVersioning** — tag-driven version at build time only. + Low risk, but leaves changelog and release-PR creation unautomated + (Repo Assist's Task 8 would keep doing that manually). +- **EasyBuild.ShipIt** — reads `CHANGELOG.md` front-matter and conventional-commit + history, computes the next semver, generates the changelog section, and opens a + release PR. Requires disabling GitHub's merge-commit option, since ShipIt's + commit parser breaks on `Merge pull request ...` commits; squash and rebase + merging both avoid that and can stay enabled side by side. +- **Status quo** — keep the manual `Directory.Build.props` edit and Repo Assist's + manual changelog PRs. Rejected: this is exactly what #234 was filed to fix. For Docker-on-release (item 3) and API docs (item 4): include now vs. defer as follow-up issues once the versioning foundation lands. @@ -27,9 +34,12 @@ as follow-up issues once the versioning foundation lands. - **EasyBuild.ShipIt** for items 1 and 2. It's the only option that covers version derivation, changelog generation, *and* release-PR creation in one tool, which directly replaces Repo Assist's existing manual Task 8 instead - of leaving two overlapping mechanisms. The repo maintainer has confirmed - switching the default merge strategy to squash-only is acceptable, which - removes the main adoption blocker. + of leaving two overlapping mechanisms. A maintainer initially proposed + squash-only as the adoption blocker's fix; concerns were raised about losing + commit-level history. This is resolved by disabling merge commits while + leaving both squash and rebase merging enabled. ShipIt's own README treats + them as equally valid, so this removes the adoption blocker without forcing + one merge style on everyone. - Items 3 (Docker image on release) and 4 (auto-generated API docs) are **out of scope for #234** and will be filed as separate follow-up issues once this ADR is accepted, so #234 isn't left open indefinitely for @@ -48,7 +58,7 @@ Full detail (decisions, trade-offs, MDR/safety notes) lives in ## Confidence -Medium. The overall direction (ShipIt + squash-merge + target split) is +Medium. The overall direction (ShipIt + disabling merge commits + target split) is sound and matches the issue thread's own analysis, but EasyBuild.ShipIt's exact CLI/config surface (front-matter schema, how it surfaces the computed version to MSBuild) is only known second-hand from an AI-bot's issue @@ -62,9 +72,12 @@ is written against it — see Step 1 below. and critically, whether it writes `Directory.Build.props` directly or expects a separate consumer (e.g. MinVer-style git-tag read) to pick up the version it computes. This determines whether `scripts/CheckSolutionVersions.fsx` needs changes. -2. **Flip the repository's default merge method to squash-only** (GitHub - repo settings — maintainer action, not a PR). Do this immediately before step 3 - merges, so the ShipIt-adoption PR is the first squash-merged one. +2. **Disable "Allow merge commits" in GitHub repo settings, leaving both + squash and rebase merging enabled** (repo settings — maintainer action, + not a PR). No urgency tied to step 3's merge: nothing runs ShipIt + unattended until step 5 lands, and every local/CI invocation already + passes `--skip-merge-commit` to tolerate the merge commits already in + history, so this can happen any time before step 5 rather than "immediately." 3. **Adopt ShipIt tooling**: add it to `.config/dotnet-tools.json`, add the confirmed front-matter to `CHANGELOG.md`, add a local dry-run entry point (FAKE target or direct `dotnet shipit` invocation): not wired into CI yet. diff --git a/docs/mdr/design-history/0000-change-log.md b/docs/mdr/design-history/0000-change-log.md index fd50fe40..3027d0cc 100644 --- a/docs/mdr/design-history/0000-change-log.md +++ b/docs/mdr/design-history/0000-change-log.md @@ -22,7 +22,7 @@ Maintain this document as a reverse-chronological log of significant design chan | Date | ADR | Summary | |------|-----|---------| -| 2026-08-05 | [ADR-0021](0021-build-system-versioning-and-release.md) | Build system versioning and release automation proposed; adopts EasyBuild.ShipIt for version/changelog/release-PR generation, squash-merge required, Repo Assist Task 8 to be retired, Docker-on-release and API docs deferred to follow-up issues. See issue #234 | +| 2026-08-05 | [ADR-0021](0021-build-system-versioning-and-release.md) | Build system versioning and release automation proposed; adopts EasyBuild.ShipIt for version/changelog/release-PR generation, merge commits disabled with squash and rebase merging both left available, Repo Assist Task 8 to be retired, Docker-on-release and API docs deferred to follow-up issues. See issue #234 | | 2026-04-30 | [ADR-0020](0020-fhir-r4-integration.md) | FHIR R4 EHR integration design proposed; stateless GenPRES with bidirectional MedicationRequest translation and G-Standard GPK coding | | 2026-04-27 | [ADR-0019](0019-shared-clinical-calculations.md) | Shared library clinical calculations accepted; BSA, age, and renal eGFR formulas available to both server and client | | 2026-04-26 | [ADR-0018](0018-nlp-dose-rule-extraction.md) | LLM-based dose-rule extraction pipeline proposed; multi-stage FSX pipeline with human review gate | diff --git a/docs/mdr/design-history/0021-build-system-versioning-and-release.md b/docs/mdr/design-history/0021-build-system-versioning-and-release.md index a64cecd2..8df19db7 100644 --- a/docs/mdr/design-history/0021-build-system-versioning-and-release.md +++ b/docs/mdr/design-history/0021-build-system-versioning-and-release.md @@ -37,8 +37,14 @@ parallel would produce competing release PRs. The repo currently merges PRs with merge commits (`939aec79 Merge pull request #436 from ...`), not squashes, even though -squash-merge is enabled at the GitHub API level. The maintainer has confirmed +squash-merge is enabled at the GitHub API level. The maintainer initially confirmed (2026-08-05) that switching the default merge method to squash-only is acceptable. +Concerns were raised that squash-only discards commit-level history on PRs where +granularity could matter. Since ShipIt's own README treats squash and rebase merging +as equally valid (both avoid the `Merge pull request ...` commits that break its commit +parsing — see the verification note below), the revised decision is to disable merge +commits but leave both squash and rebase merging enabled, so each contributor chooses +per PR instead of one strategy being forced on everyone. This document is ADR-0021, the next number available in [the design-history log](0000-change-log.md). @@ -57,7 +63,7 @@ at a time, rather than as a single documentation pass. | # | Choice | Rationale | |---|--------|-----------| | 1 | EasyBuild.ShipIt over MinVer/Nerdbank.GitVersioning | Only option that covers versioning **and** changelog generation **and** release-PR creation in one tool; MinVer/Nerdbank would still leave changelog automation and Repo Assist's Task 8 duplication unresolved | -| 2 | Squash-merge required as the default merge method | ShipIt derives changelog entries from one commit per PR; the maintainer has approved this process change | +| 2 | Merge commits disabled; squash and rebase merging both left enabled | ShipIt needs each PR to land without a `Merge pull request ...` commit to parse cleanly; squash and rebase both satisfy that per ShipIt's own README, so contributors keep the choice instead of being forced to squash away commit-level history | | 3 | Retire Repo Assist Task 8 in the same PR that turns on CI-driven ShipIt | Prevents two bots from proposing competing release PRs on the same merge | | 4 | Docker-on-release (item 3) and API docs (item 4) deferred to new follow-up issues | Both are greenfield efforts (no existing docfx/GitHub Pages/Docker-publish infrastructure) with no dependency on the versioning work landing first being a blocker either way; keeping them separate lets #234 close on a coherent, reviewable scope | | 5 | `Build` FAKE target split into `ServerBuild`/`ClientBuild`, with `Build` kept as an umbrella target | Existing dependency chains (`Build ==> ServerTests`, `Build ==> CheckVersions`, `Build ==> Run`) keep working unchanged; new targets are additive | @@ -88,12 +94,13 @@ This determines whether `scripts/CheckSolutionVersions.fsx` needs to change at a **Negative / Trade-offs**: -- Switching to squash-merge changes the commit history shape project-wide, - not just for build-system PRs — every future PR merge is affected. -- `CHANGELOG.md`'s current rich, hand-written prose entries (see any - `[Unreleased]` entry today) become leaner, PR-title-derived entries under - ShipIt. The `=== changelog ===` block convention in a PR body (if ShipIt - supports pulling it in, per step 1's verification) is the escape hatch for +- Disabling merge commits changes the commit history shape project-wide, not just + for build-system PRs, every future PR merge is affected. Squash and rebase + remain a per-PR choice, so no one is forced to lose commit-level history, but + `Merge pull request ...` commits stop being an option entirely. +- `CHANGELOG.md`'s current rich, hand-written prose entries (see any `[Unreleased]` + entry today) become leaner, PR-title-derived entries under ShipIt. + The `=== changelog ===` block convention in a PR body is the escape hatch for entries that need more detail than a title provides. - Items 3 and 4 remain unaddressed after #234 closes; they need their own issues and, eventually, their own ADRs or ADR amendments.