Repository navigation
docs(inkless:sync): align sync guides with PEP 440 version-consistency fixes - #780
Merged
Merged
Conversation
…y fixes The 4.3.1 release sync (inkless-4.3-sync-4.3.1) and an earlier main (trunk) sync both hit CI failures from the same root cause: upstream's verifyVersionConsistency and pip-install dry-run checks require tests/kafkatest/__init__.py, tests/kafkatest/version.py, committer-tools/kafka-merge-pr.py, and the streams/quickstart POMs to carry the inkless-suffixed version, and __init__.py's __version__ must additionally stay PEP 440 compliant (packaging.version.Version rejects a bare ".inkless"/"-inkless" suffix; use the "+inkless" local version label instead). None of the sync docs described this pattern correctly or completely: RELEASE-SYNC-GUIDE.md and RELEASE-SYNC-SESSION-TEMPLATE.md still had the old, invalid ".inkless"/"-inkless-SNAPSHOT"/plain-POM guidance; RELEASE-SYNC-ACTION-PLAN.md and RELEASE-SYNC-PROMPT.md repeated the same stale patterns; and the main-sync docs (MAIN-SYNC-ACTION-PLAN.md, MAIN-SYNC-PROMPT.md, MAIN-SYNC-SESSION-TEMPLATE.md, CONFLICT-RESOLUTION-STRATEGY.md) didn't mention these auxiliary version files at all, despite hitting the same failure during a main sync. Update every affected doc with the correct PEP 440 pattern and the "must match gradle.properties exactly" rule, and add a verifyVersionConsistency checklist item to the main-sync session template, so future syncs of either kind don't repeat these CI failures. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Several updated main-sync/release-sync doc statements still don’t match the repository’s enforced version rules (PEP 440 snapshot mapping, kafka-merge-pr.py dropping -SNAPSHOT, and incorrect streams/quickstart/*.pom globs).
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the inkless-sync/ documentation to prevent recurring sync CI failures by documenting the required version-alignment rules enforced by :verifyVersionConsistency and Python PEP 440 parsing.
Changes:
- Updates release-sync guides/templates/prompts to document the PEP 440-compliant
+inklessPython version pattern and the “keep versions consistent” rule. - Updates main-sync guides/templates/prompts to include the auxiliary version files and a
./gradlew verifyVersionConsistencychecklist item. - Updates guidance for the Streams quickstart POMs to align with what the Gradle verification task enforces.
File summaries
| File | Description |
|---|---|
| inkless-sync/RELEASE-SYNC-SESSION-TEMPLATE.md | Updates the conflict-resolution checklist with corrected version rules and POM expectations. |
| inkless-sync/RELEASE-SYNC-PROMPT.md | Updates the release-sync prompt’s version-file guidance to use the PEP 440 +inkless pattern. |
| inkless-sync/RELEASE-SYNC-GUIDE.md | Updates the release-sync guide’s conflict patterns and examples for version consistency. |
| inkless-sync/RELEASE-SYNC-ACTION-PLAN.md | Updates the release-sync action plan with corrected PEP 440 notes and version-consistency guidance. |
| inkless-sync/MAIN-SYNC-SESSION-TEMPLATE.md | Adds auxiliary version files and a verifyVersionConsistency checklist item to the main-sync template. |
| inkless-sync/MAIN-SYNC-PROMPT.md | Adds main-sync prompt guidance for auxiliary version files and running verifyVersionConsistency. |
| inkless-sync/MAIN-SYNC-ACTION-PLAN.md | Adds a main-sync action-plan step covering auxiliary version files and verifyVersionConsistency. |
| inkless-sync/CONFLICT-RESOLUTION-STRATEGY.md | Adds auxiliary version-file rules to the general conflict-resolution strategy. |
Review details
Suppressed comments (4)
inkless-sync/MAIN-SYNC-PROMPT.md:99
committer-tools/kafka-merge-pr.pydoesn't always matchgradle.propertiesexactly on-SNAPSHOTversions:verifyVersionConsistencyexpectsDEFAULT_FIX_VERSIONto drop the-SNAPSHOTsuffix (seebuild.gradle'sgetVersionTargets).
- `tests/kafkatest/version.py`, `committer-tools/kafka-merge-pr.py`, and
`streams/quickstart/*.pom`: must match `gradle.properties` exactly.
inkless-sync/MAIN-SYNC-ACTION-PLAN.md:72
committer-tools/kafka-merge-pr.pyis validated againstgradle.propertieswith the-SNAPSHOTsuffix removed (the current trunk values differ in exactly this way), so saying it must match exactly is misleading.
`tests/kafkatest/version.py`, `committer-tools/kafka-merge-pr.py`, and the
`streams/quickstart/*.pom` files (must match `gradle.properties` exactly). Run
inkless-sync/MAIN-SYNC-SESSION-TEMPLATE.md:51
committer-tools/kafka-merge-pr.pyusesDEFAULT_FIX_VERSIONwithout the-SNAPSHOTsuffix on trunk (andverifyVersionConsistencyenforces that), so it shouldn't be described as matchinggradle.propertiesexactly on snapshot versions.
| | committer-tools/kafka-merge-pr.py | Must match `gradle.properties` exactly | |
inkless-sync/CONFLICT-RESOLUTION-STRATEGY.md:30
committer-tools/kafka-merge-pr.pyis validated againstgradle.propertieswith-SNAPSHOTremoved (seebuild.gradle'sgetVersionTargets), so "must match gradle.properties exactly" is inaccurate for snapshot versions.
| `tests/kafkatest/version.py`, `committer-tools/kafka-merge-pr.py`, `streams/quickstart/*.pom` | Must match `gradle.properties` exactly (for example `4.3.0-inkless-SNAPSHOT`); the `:verifyVersionConsistency` Gradle task enforces this |
- Files reviewed: 8/8 changed files
- Comments generated: 9
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Add missing `dev` Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
jeqo
reviewed
Sep 2, 2026
jeqo
approved these changes
Sep 7, 2026
jeqo
added a commit
that referenced
this pull request
Sep 9, 2026
…nsistency gate (#794) branch-consistency.sh --check is the release gate: the release workflow runs it per active branch and refuses to tag while any actionable main commit is missing. The check matches by PR number and only excluded titles starting with sync(, fix(sync), docs(sync), or refactor(sync). Sync-tooling PRs use the scopes inkless-sync, inkless:sync, and inkless:release-sync, so they did not match and the gate counted them as missing on every release branch. They only touch inkless-sync/, which no release branch reads: the sync guides copy main's inkless-sync/ into the sync worktree. Since 0.47 that covered #768, #770, #776, and #780 on inkless-4.1 and inkless-4.2, and #780 on inkless-4.3. Match any conventional-commit type with those scopes, in addition to the existing sync( prefix. inkless:ci and inkless:release commits keep counting: they change workflows, build files, and docs that release branches do carry. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
jeqo
added a commit
that referenced
this pull request
Sep 9, 2026
…nsistency gate (#794) branch-consistency.sh --check is the release gate: the release workflow runs it per active branch and refuses to tag while any actionable main commit is missing. The check matches by PR number and only excluded titles starting with sync(, fix(sync), docs(sync), or refactor(sync). Sync-tooling PRs use the scopes inkless-sync, inkless:sync, and inkless:release-sync, so they did not match and the gate counted them as missing on every release branch. They only touch inkless-sync/, which no release branch reads: the sync guides copy main's inkless-sync/ into the sync worktree. Since 0.47 that covered #768, #770, #776, and #780 on inkless-4.1 and inkless-4.2, and #780 on inkless-4.3. Match any conventional-commit type with those scopes, in addition to the existing sync( prefix. inkless:ci and inkless:release commits keep counting: they change workflows, build files, and docs that release branches do carry. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
jeqo
added a commit
that referenced
this pull request
Sep 9, 2026
…nsistency gate (#794) branch-consistency.sh --check is the release gate: the release workflow runs it per active branch and refuses to tag while any actionable main commit is missing. The check matches by PR number and only excluded titles starting with sync(, fix(sync), docs(sync), or refactor(sync). Sync-tooling PRs use the scopes inkless-sync, inkless:sync, and inkless:release-sync, so they did not match and the gate counted them as missing on every release branch. They only touch inkless-sync/, which no release branch reads: the sync guides copy main's inkless-sync/ into the sync worktree. Since 0.47 that covered #768, #770, #776, and #780 on inkless-4.1 and inkless-4.2, and #780 on inkless-4.3. Match any conventional-commit type with those scopes, in addition to the existing sync( prefix. inkless:ci and inkless:release commits keep counting: they change workflows, build files, and docs that release branches do carry. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
jeqo
added a commit
that referenced
this pull request
Sep 9, 2026
…nsistency gate (#794) branch-consistency.sh --check is the release gate: the release workflow runs it per active branch and refuses to tag while any actionable main commit is missing. The check matches by PR number and only excluded titles starting with sync(, fix(sync), docs(sync), or refactor(sync). Sync-tooling PRs use the scopes inkless-sync, inkless:sync, and inkless:release-sync, so they did not match and the gate counted them as missing on every release branch. They only touch inkless-sync/, which no release branch reads: the sync guides copy main's inkless-sync/ into the sync worktree. Since 0.47 that covered #768, #770, #776, and #780 on inkless-4.1 and inkless-4.2, and #780 on inkless-4.3. Match any conventional-commit type with those scopes, in addition to the existing sync( prefix. inkless:ci and inkless:release commits keep counting: they change workflows, build files, and docs that release branches do carry. Co-authored-by: Claude Fable 5.1 <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.
The 4.3.1 release sync (inkless-4.3-sync-4.3.1) and an earlier main (trunk) sync both hit CI failures from the same root cause: upstream's verifyVersionConsistency and pip-install dry-run checks require tests/kafkatest/init.py, tests/kafkatest/version.py, committer-tools/kafka-merge-pr.py, and the streams/quickstart POMs to carry the inkless-suffixed version, and init.py's version must additionally stay PEP 440 compliant (packaging.version.Version rejects a bare ".inkless"/"-inkless" suffix; use the "+inkless" local version label instead).
None of the sync docs described this pattern correctly or completely: RELEASE-SYNC-GUIDE.md and RELEASE-SYNC-SESSION-TEMPLATE.md still had the old, invalid ".inkless"/"-inkless-SNAPSHOT"/plain-POM guidance; RELEASE-SYNC-ACTION-PLAN.md and RELEASE-SYNC-PROMPT.md repeated the same stale patterns; and the main-sync docs (MAIN-SYNC-ACTION-PLAN.md, MAIN-SYNC-PROMPT.md, MAIN-SYNC-SESSION-TEMPLATE.md, CONFLICT-RESOLUTION-STRATEGY.md) didn't mention these auxiliary version files at all, despite hitting the same failure during a main sync.
Update every affected doc with the correct PEP 440 pattern and the "must match gradle.properties exactly" rule, and add a verifyVersionConsistency checklist item to the main-sync session template, so future syncs of either kind don't repeat these CI failures.