Skip to content

docs: hidden commit types ship no release; refactor is one of them #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TzuH-Hsu merged 1 commit into from
Sep 16, 2026
Merged

docs: hidden commit types ship no release; refactor is one of them #71

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion skills/branch-and-commit/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,18 @@ code that closes it. Getting the format right keeps `git log`, the changelog, an
| `feat` | New capability | Minor bump, "Features" section |
| `fix` | Bug fix | Patch bump, "Bug Fixes" section |
| `perf` | Performance improvement | Patch bump |
| `refactor` | Restructure, no behavior change | Patch bump |
| `refactor` | Restructure, no behavior change | No version bump |
| `docs` | Documentation only | No version bump |
| `chore` | Maintenance, tooling | No version bump |
| `ci` | CI/CD workflow changes | No version bump |
| `test` | Test-only changes | No version bump |

"No version bump" means release-please does not open a release PR for it at
all — it is a hidden type. A change users will notice that only fits a hidden
type (a new CI gate under `ci`, a behaviour-changing `refactor`) still has to
ship: put a `Release-As: X.Y.Z` footer in the PR body (the body becomes the
Comment on lines +35 to +37

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove the behavior-changing refactor example

A user-visible behavior change cannot be a refactor under this table's own definition of “no behavior change”; it should be classified as feat, fix, or perf. Keeping it hidden and adding Release-As may cut a tag, but the change remains excluded from the generated changelog, so this example teaches maintainers to publish an undocumented behavioral change.

Useful? React with 👍 / 👎.

@TzuH-Hsu TzuH-Hsu Sep 16, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5155034: the refactor example is gone; the text now says a user-visible change is usually a feat or fix, and that a hidden type also keeps it out of the changelog — Release-As is only for a genuinely hidden type that still needs a tag.

squash commit's message) and release-please cuts that version.

4. Breaking changes append `!` after the type (`feat!:`) or add a `BREAKING CHANGE:`
footer — either triggers a major bump. Use whichever is more visible for the
change; don't rely on prose in the body alone.
Expand Down
2 changes: 2 additions & 0 deletions skills/release-management/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,8 @@ gh release edit v0.2.0 --notes "TLDR: ...\n\n$(gh release view v0.2.0 --json bod

## Pitfalls

- Shipping a release-worthy change under a hidden type (`ci`, `chore`, `docs`, `refactor`, `test`) and waiting for a release PR that never comes — release-please logs `No user facing commits found … skipping`. Either the type was wrong (`feat`/`fix`), or add `Release-As: X.Y.Z` to the PR body so the squash commit carries it (see `skills/branch-and-commit` rule 3).

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document the Release-As exception to derived versions

For a correctly classified hidden-type change, this instruction requires the maintainer to choose an exact X.Y.Z, while rule 2 still states without exception that the version is derived rather than chosen. Define how the override's SemVer level is selected and identify it as an explicit exception; otherwise agents following the two normative instructions have no consistent way to determine the footer value.

Useful? React with 👍 / 👎.

@TzuH-Hsu TzuH-Hsu Sep 16, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5155034: rule 2 names the exception and fixes the level — Release-As is always the current version plus one patch; wanting more means the type was wrong. The pitfall and branch-and-commit rule 3 point at it.


- Publishing or delivering a repository whose `LICENSE` still names the upstream template author — `head -3 LICENSE` before anything leaves the building. For client work an inherited MIT grants the client, and everyone else, far more than the commission contract does, and it cannot be withdrawn (`docs/setup/licensing.md`).
- Enabling auto-merge on the release-please PR "to save a click" — this defeats the entire point of the human gate described in ADR-0002; the `push:main` race is only closed because a human reviews before merge.
- Shipping release notes with only the generated Conventional Commit list and no TLDR — accurate for engineers, meaningless for the actual audience of a release announcement.
Expand Down
Loading