Tighten i18n docs: do not bump @version or write CHANGELOG#527
Merged
Conversation
After Phase 2 rollout (May 8 2026 — i18n migration on 7 phoenix_kit_<x> modules), the maintainer overwrote @Version and CHANGELOG.md on every merge. The rule is now uniform across phoenix_kit core AND every child module: contributors and agents do not edit either; the maintainer derives both from commit messages at release time. guides/per-module-i18n.md - Setup checklist step 11 deleted; replaced with a callout pointing at the new ownership section - Section "Version bump and CHANGELOG (owned packages)" replaced with "Version and CHANGELOG ownership" — explicitly forbids both edits for ALL packages including owned forks - Retrofit checklist last item flipped from "do" to "do NOT" dev_docs/instructions/2026-05-08-per-module-i18n-procedure.md - Step 8 renamed and inverted: "Do NOT bump @Version. Do NOT write CHANGELOG entry." Includes rollout-history note documenting why the rule was tightened - Step 9 (stage and commit) gained two pre-commit verification grep commands: must confirm @Version and CHANGELOG are unchanged
ddon
pushed a commit
that referenced
this pull request
May 9, 2026
The CHANGELOG verification snippet introduced in PR #527 used `git diff --staged CHANGELOG.md | head -1 && echo "..."`, but `head -1` exits 0 on empty input, so the warning always fired regardless of whether CHANGELOG.md was actually staged — training contributors to ignore it. Replaced with a name-only check that fires only on a real staged change. Also tightened the @Version grep so it matches the actual `@version "…"` attribute and skips substrings inside heredocs or comments. Minor phrasing fix in the public guide. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6 tasks
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.
Summary
After Phase 2 of the per-module i18n rollout merged across 7 child packages, the maintainer overwrote
@versionandCHANGELOG.mdon every single merge. The earlier docs (the public guide added in #522 and the internal playbook atdev_docs/instructions/2026-05-08-per-module-i18n-procedure.md) instructed agents to bump@versionand write a CHANGELOG entry — that advice produced merge friction on every PR.This PR inverts the rule across both documents: contributors and agents do not edit
@versionand do not add CHANGELOG entries — forphoenix_kitcore and everyphoenix_kit_<x>child module. The maintainer derives both from PR commit messages at release time.Changes
guides/per-module-i18n.md@versionand add a CHANGELOG entry") deleted; replaced with an explicit callout pointing at the new ownership section.dev_docs/instructions/2026-05-08-per-module-i18n-procedure.md@versionand write CHANGELOG" → "Do NOT bump@version. Do NOT write a CHANGELOG entry." Includes a rollout-history note documenting why the rule was tightened (Phase 2 maintainer overwrites).Why this is a uniform rule (not just for core)
Earlier convention treated
phoenix_kitcore differently from owned forks — core's CHANGELOG was maintainer-owned, but forphoenix_kit_newslettersand friends the team was the maintainer and the original guide/playbook said "you do bump version and write CHANGELOG entry". Phase 2 rollout proved that distinction false in practice: the maintainer reviewed each PR and rewrote both lines anyway, every time, because:mix.exs@versionandCHANGELOG.mdfirst-entry header are the two most conflict-prone lines in any active package; pre-edits compound the noise.The new rule eliminates all three. Contributors put their effort into commit messages; the maintainer owns the rest.
Test plan
Out of scope
@versionandCHANGELOG.mdon each. The CRM PR (Add live data updates system for admin panels and comprehensive session management system for admin interface #5 inphoenix_kit_crm, still open) carries the old rule's@versionbump + CHANGELOG entry; the maintainer can squash those out at merge time, same as the others.