From e0fcc861f2766db27d536c69cabd912ac83f8ed8 Mon Sep 17 00:00:00 2001 From: 0xGREG Date: Tue, 28 Apr 2026 21:45:22 +0000 Subject: [PATCH] Document DEFAULT_TITLE_SOURCE pull request title setting (#391) Adds documentation for the `DEFAULT_TITLE_SOURCE` setting. - Added `DEFAULT_TITLE_SOURCE` to the config cheat sheet under `[repository.pull-request]` - Added a "Default pull request title" section to the pull request usage docs explaining both modes (`first-commit` and `auto`) --------- Co-authored-by: Nicolas Reviewed-on: https://gitea.com/gitea/docs/pulls/391 Reviewed-by: Nicolas Co-authored-by: 0xGREG Co-committed-by: 0xGREG --- docs/administration/config-cheat-sheet.md | 3 +++ docs/usage/issues-prs/pull-request.md | 16 ++++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/docs/administration/config-cheat-sheet.md b/docs/administration/config-cheat-sheet.md index cd81d1cd..ddf9be8f 100644 --- a/docs/administration/config-cheat-sheet.md +++ b/docs/administration/config-cheat-sheet.md @@ -169,6 +169,9 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build - `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author. - `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo. - `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: Set the default value for "Delete pull request branch after merge by default" for new repositories. +- `DEFAULT_TITLE_SOURCE`: **first-commit**: Default source for the pull request title when opening a new PR. Valid options: + - `first-commit`: Uses the oldest commit's summary as the title. If there are multiple commits, still uses the first commit's message. + - `auto`: Uses the commit's summary when the PR contains a single commit; when there are multiple commits, converts the branch name into a human-readable title by normalizing separators and casing. ### Repository - Issue (`repository.issue`) diff --git a/docs/usage/issues-prs/pull-request.md b/docs/usage/issues-prs/pull-request.md index e9800910..97dde0f8 100644 --- a/docs/usage/issues-prs/pull-request.md +++ b/docs/usage/issues-prs/pull-request.md @@ -55,6 +55,22 @@ WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP] The first value of the list will be used in helpers. +## Default pull request title + +When opening a new pull request, Gitea pre-fills the title field. The source of that title is controlled by the `DEFAULT_TITLE_SOURCE` setting in `app.ini`: + +```ini +[repository.pull-request] +DEFAULT_TITLE_SOURCE = first-commit +``` + +Two modes are available: + +- **`first-commit`** (default): The title is taken from the summary line of the oldest commit in the branch. This applies regardless of how many commits are included in the PR. +- **`auto`**: When the PR contains a single commit, its summary line is used as the title (same as `first-commit` for one commit). When the PR contains multiple commits, Gitea converts the branch name into a human-readable sentence: dashes, underscores, and `camelCase` word boundaries are replaced with spaces, and the first letter is capitalized. + +Example: branch name `fix-user-login-flow` with multiple commits produces the title `Fix user login flow` under `auto`, but would use the oldest commit's message under `first-commit`. + ## Pull Request Templates You can find more information about pull request templates at the page [Issue and Pull Request templates](issue-pull-request-templates.md).