Skip to content

Tighten i18n docs: do not bump @version or write CHANGELOG#527

Merged
ddon merged 1 commit into
BeamLabEU:devfrom
timujinne:feature/i18n-rule-no-version-bump
May 9, 2026
Merged

Tighten i18n docs: do not bump @version or write CHANGELOG#527
ddon merged 1 commit into
BeamLabEU:devfrom
timujinne:feature/i18n-rule-no-version-bump

Conversation

@timujinne
Copy link
Copy Markdown
Contributor

Summary

After Phase 2 of the per-module i18n rollout merged across 7 child packages, the maintainer overwrote @version and CHANGELOG.md on every single merge. The earlier docs (the public guide added in #522 and the internal playbook at dev_docs/instructions/2026-05-08-per-module-i18n-procedure.md) instructed agents to bump @version and 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 @version and do not add CHANGELOG entries — for phoenix_kit core and every phoenix_kit_<x> child module. The maintainer derives both from PR commit messages at release time.

Changes

guides/per-module-i18n.md

  • Setup checklist step 11 ("Bump module @version and add a CHANGELOG entry") deleted; replaced with an explicit 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 locally-owned forks.
  • Retrofit checklist last item flipped from "do" to "do NOT", with a pointer at the ownership section.

dev_docs/instructions/2026-05-08-per-module-i18n-procedure.md

  • Step 8 renamed: "Bump @version and 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).
  • Step 9 (stage and commit) gained two pre-commit verification grep commands:
    git diff --staged mix.exs | grep -E '^\+.*@version' && echo "STILL TOUCHED @version — revert that line"
    git diff --staged CHANGELOG.md | head -1 && echo "CHANGELOG should be clean — revert it from HEAD"
    These flag accidental edits before commit.

Why this is a uniform rule (not just for core)

Earlier convention treated phoenix_kit core differently from owned forks — core's CHANGELOG was maintainer-owned, but for phoenix_kit_newsletters and 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:

  1. Squash + release timing. A feature PR + follow-up fix often merge in the same release; coordinating two version-line edits across two PRs creates merge conflicts.
  2. Release notes assembly. The maintainer reads commit bodies to write the CHANGELOG — so the source of truth is the commit message, not a separately-edited file.
  3. Merge conflict frequency. mix.exs @version and CHANGELOG.md first-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

  • No code changes; docs-only.
  • Verified the public guide's Quick Start, Setup checklist, Step-by-step setup, Greenfield example, Retrofitting checklist, Test pattern, Common pitfalls, and Where-this-fits-in-the-rollout sections still flow consistently after the inversion.
  • Verified the playbook's gotchas 1-16 still reference the correct step numbers.
  • Maintainer review.

Out of scope

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 ddon merged commit 8036442 into BeamLabEU:dev May 9, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants