From c65c18364cd76f3bdd8354545f0d5fe7d22be826 Mon Sep 17 00:00:00 2001 From: mohamed-elkholy95 Date: Fri, 29 May 2026 15:52:53 -0400 Subject: [PATCH 1/2] docs: align release workflow and changelog convention with actual process AGENTS.md documented a stale Keep-a-Changelog style that no longer matches the repo: a MAJOR.MINOR.PATCH scheme with 1.x examples, bump-* branches, renaming [Unreleased] to [X.Y] - YYYY-MM-DD, and git tag X.Y / git push --tags. The actual process is 0.MINOR.PATCH, release/X.Y.Z branches, a retained empty ## Unreleased plus a ## X.Y.Z (YYYY-MM-DD) section, the npm run sync step for the docs changelog, and annotated vX.Y.Z tags. Correct the Versioning and Release workflow sections to match. Also drop the now-dead title-rewrite and subsection-strip transforms in sync-changelog.mjs: the root CHANGELOG already uses ## X.Y.Z (date) headers and ### What changed in this release subsections, so both regexes were no-ops. The generated docs changelog is byte-identical before and after this change. --- AGENTS.md | 36 +++++++++++++++++++-------------- docs/scripts/sync-changelog.mjs | 11 +++------- 2 files changed, 24 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 98492b77..f12a6fc9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -357,13 +357,13 @@ Never add AI-generated/co-author trailers or tool footers to commits or PR descr ## Versioning -The project follows a **minor-bump-only** versioning scheme (`MAJOR.MINOR.PATCH`): +The project follows a `0.MINOR.PATCH` versioning scheme: -- Patch version is always `0`. Never bump it. -- Minor version is bumped for any change: features, improvements, bug fixes, etc. -- Major version changes only by explicit manual decision. +- Major version stays `0`; there is no `1.0.0` milestone planned on this line. +- Minor version is a running counter, bumped for every release: features, improvements, bug fixes, etc. +- Patch version is reserved for hotfixes against an already-released minor; it is normally `0`. -Examples: `1.0.0` -> `1.1.0` -> `1.2.0`; never `1.0.1`. +Examples: `0.24.0` -> `0.25.0` -> `0.26.0`; a hotfix against `0.25.0` would be `0.25.1`. This applies to release packages in the root project and `packages/*` unless a release task targets an independently versioned package. Do not normalize `sdks/*` or `examples/*` versions unless the @@ -372,13 +372,19 @@ user or release workflow explicitly asks for that package. ## Release workflow 1. Ensure `main` is up to date. -2. Create a release branch, e.g. `bump-1.42` or `bump-pythinker-host-1.43`. -3. Update `CHANGELOG.md`: rename `[Unreleased]` to `[1.42] - YYYY-MM-DD`. -4. Update `pyproject.toml` version. -5. Run `uv sync` to align `uv.lock`. -6. Commit the branch and open a PR. -7. Merge the PR, then switch back to `main` and pull latest. -8. Tag and push: - - `git tag 1.42` or `git tag pythinker-host-1.43` - - `git push --tags` -9. GitHub Actions handles publishing after tags are pushed. +2. Create a release branch, e.g. `release/0.25.0`. +3. Update `CHANGELOG.md`: move the `## Unreleased` entries into a new + `## X.Y.Z (YYYY-MM-DD)` section and leave `## Unreleased` in place (emptied). + Then regenerate the docs copy with `npm run sync` from `docs/` — do not edit + `docs/en/release-notes/changelog.md` by hand — add a `## X.Y.Z (date)` entry to + `docs/en/release-notes/breaking-changes.md`, and update the README "What's New" + section plus the version strings across the install scripts and packaging files. +4. Update `pyproject.toml` version and run `uv sync` to align `uv.lock`. +5. Commit the branch and open a PR. `main` is protected, so the required checks + (and CodeRabbit) must pass before the PR can be squash-merged. +6. After merge, switch back to `main` and pull latest. +7. Tag the merged commit and push: + - `git tag -a v0.25.0 -m "pythinker-code 0.25.0"` + - `git push origin v0.25.0` +8. GitHub Actions (`release-pythinker-cli.yml`) publishes to PyPI/TestPyPI and the + GitHub Release after the tag is pushed. diff --git a/docs/scripts/sync-changelog.mjs b/docs/scripts/sync-changelog.mjs index f7c434d1..2e5e865d 100644 --- a/docs/scripts/sync-changelog.mjs +++ b/docs/scripts/sync-changelog.mjs @@ -34,14 +34,9 @@ content = content.replace(/\n*/g, ""); // Remove the "# Changelog" title (we'll add our own header) content = content.replace(/^# Changelog\n+/, ""); -// Convert title format: ## [0.69] - 2025-12-29 -> ## 0.69 (2025-12-29) -content = content.replace( - /^## \[([^\]]+)\] - (\d{4}-\d{1,2}-\d{1,2})/gm, - "## $1 ($2)" -); - -// Remove subsection headers like ### Added, ### Changed, ### Fixed -content = content.replace(/^### (Added|Changed|Fixed|Improved|Tools|SDK)\n+/gm, ""); +// Release headers (`## X.Y.Z (YYYY-MM-DD)`) and the `### What changed in this +// release` subsections are copied through verbatim — the root CHANGELOG already +// uses the format the docs site renders, so no title rewriting is needed. // The docs changelog is emitted under docs/en/release-notes/, so links that are // correct from the repository root need to be adjusted for VitePress dead-link From 6ace1882cd46be1e2f58fef30a9a87d078c960f1 Mon Sep 17 00:00:00 2001 From: mohamed-elkholy95 Date: Fri, 29 May 2026 17:01:27 -0400 Subject: [PATCH 2/2] ci: run pythinker-code checks on every PR check / test (3.x) / release-validate are required status checks, but the pull_request trigger was path-filtered to code paths. Docs-only (and sdks/**- or examples/**-only) PRs never ran them, so the required contexts never reported and the PR stayed BLOCKED under strict + enforce_admins with no clean override. Drop the pull_request path filter so these checks run on every PR: exactly one check run per context (no duplicate-context false-greens) and real signal on every change. The push trigger keeps its path filter unchanged. --- .github/workflows/ci-pythinker-cli.yml | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci-pythinker-cli.yml b/.github/workflows/ci-pythinker-cli.yml index d9f0e0f3..0c60bb52 100644 --- a/.github/workflows/ci-pythinker-cli.yml +++ b/.github/workflows/ci-pythinker-cli.yml @@ -1,17 +1,12 @@ name: CI (pythinker-code) on: + # No path filter on pull_request: check / test / release-validate are required + # status checks, so they must run on every PR. Path-filtering them left + # docs-only (and sdks/examples-only) PRs permanently blocked — the required + # contexts never reported. Running the real checks on every PR keeps one check + # run per context (no duplicate-context false-greens) and gives real signal. pull_request: - paths: - - ".github/workflows/**" - - "packages/**" - - "src/**" - - "tests/**" - - "tests_e2e/**" - - "tests_ai/**" - - "web/**" - - "pyproject.toml" - - "uv.lock" push: branches: - main