[TRUNK-17691] Document custom merge commit titles via PR body directive#456
[TRUNK-17691] Document custom merge commit titles via PR body directive#456samgutentag wants to merge 1 commit intomainfrom
Conversation
Add docs for the `merge-commit-title:` directive that lets users specify a custom merge commit title by adding it on its own line in the PR body. Updates the submit/cancel page, FAQ, and advanced settings. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Merging to
|
samgutentag
changed the title
|
Claude finished @samgutentag's task in 2m 5s —— View job Review complete
The documentation additions are well-structured and the cross-linking between pages is a good pattern. I left 5 inline comments: Blocking concerns:
Non-blocking suggestions:
Recommend resolving the three open questions in the PR body before merging, as the answers may require edits to the documentation content. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| * **Merge Commit**: Preserves all individual commit messages from the PR and creates an additional merge commit message | ||
| * **Rebase**: Preserves all individual commit messages from the PR as they are replayed onto the target branch | ||
|
|
||
| You can override the merge commit title for any PR by adding `merge-commit-title: Your Custom Title` on its own line in the PR body. See [Custom merge commit titles](../administration/advanced-settings.md#custom-merge-commit-titles) for details. |
There was a problem hiding this comment.
The cross-reference here links to advanced-settings.md#custom-merge-commit-titles, but that section is a brief summary which itself redirects the reader back to reference.md for "more details and examples." This creates an unnecessary two-hop navigation path for users.
Since the comprehensive documentation (syntax, full example, usage guidance) lives in reference.md, consider linking there directly:
| You can override the merge commit title for any PR by adding `merge-commit-title: Your Custom Title` on its own line in the PR body. See [Custom merge commit titles](../administration/advanced-settings.md#custom-merge-commit-titles) for details. | |
| You can override the merge commit title for any PR by adding `merge-commit-title: Your Custom Title` on its own line in the PR body. See [Custom merge commit titles](../using-the-queue/reference.md#custom-merge-commit-titles) for details. |
|
|
||
| When Trunk merges the PR, it uses this title instead of the default GitHub-generated title. When the directive is not present, the default behavior is preserved. | ||
|
|
||
| This is useful for teams that follow conventional commit formats, include ticket numbers in merge commits, or want cleaner git history. |
There was a problem hiding this comment.
Minor grammar nit: "cleaner git history" should be "a cleaner git history."
| This is useful for teams that follow conventional commit formats, include ticket numbers in merge commits, or want cleaner git history. | |
| This is useful for teams that follow conventional commit formats, include ticket numbers in merge commits, or want a cleaner git history. |
| merge-commit-title: feat(auth): add OAuth2 login flow [PROJ-123] | ||
| ``` | ||
|
|
||
| {% hint style="info" %} |
There was a problem hiding this comment.
The hint says the directive "only customizes the commit title" but it would be clearer to echo the directive name and say "merge commit title" — matching the phrasing used in the heading and throughout the section:
| {% hint style="info" %} | |
| The `merge-commit-title:` directive only customizes the merge commit **title**. The commit body follows the usual behavior for your configured [merge method](../administration/advanced-settings.md#merge-method). |
|
|
||
| ## Custom merge commit titles | ||
|
|
||
| You can specify a custom merge commit title for any PR by adding a `merge-commit-title:` directive on its own line anywhere in the PR body: |
There was a problem hiding this comment.
Potential accuracy issue (open question #1 from PR): This sentence doesn't restrict which merge methods the directive applies to, but the PR itself asks: "Does merge-commit-title: work with rebase merge method, or only squash and merge commit?"
If the directive only works with Squash and Merge Commit methods (not Rebase), the docs here will be misleading for users on a Rebase workflow. Before merging, please verify this and either:
- Confirm it works with all three methods (no change needed), or
- Add a note scoping it, e.g.: "This directive applies to Squash and Merge Commit methods. It has no effect when using the Rebase merge method."
|
|
||
| You can specify a custom merge commit title for any PR by adding a `merge-commit-title:` directive on its own line anywhere in the PR body: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Open questions #2 & #3 from PR (case sensitivity & length limits): The docs don't mention whether the directive is case-sensitive or if there are character/length limits on the title value. If these are relevant constraints, they should be documented here or in the hint block. For example:
Note: The directive is case-sensitive —
Merge-Commit-Title:will not be recognized. Titles have a maximum length of X characters.
Resolve these before merging to avoid a follow-up correction.
1 participant
Summary
• Added new "Custom merge commit titles" section to the Submit and cancel pull requests page with syntax, examples, and usage guidance
• Updated the FAQ "How does Trunk handle commit messages" to reference the new
merge-commit-title:directive• Added "Custom merge commit titles" subsection under Merge Method in Advanced Settings
Linear tickets
Context links
Files changed
merge-queue/using-the-queue/reference.md— new section with syntax and examplemerge-queue/reference/common-problems.md— updated FAQ answermerge-queue/administration/advanced-settings.md— new subsection under Merge MethodOpen questions
merge-commit-title:work with rebase merge method, or only squash and merge commit?Test plan
🤖 Generated with Claude Code