When creating, updating, or merging pull requests, and when writing text that will appear on GitHub, follow the standards below. If the repo's documentation or PR template specifies otherwise, follow that instead. For writing style, follow the standards in the kuden:writing skill.
Guideline 1. Write what was solved in the title
Write the title as a single sentence stating why the change is being made and what changes as a result. If the reason and how the behavior changes are stated, a reviewer can judge the validity from the title alone.
- Don't trace the implementation steps. A title that lines up function names or file paths newly created in that PR makes no sense until the diff is read
- Don't only write that the symptom is removed. "Remove warning" could be read as suppressing it, and doesn't convey the nature of the change. Write the reason and the content of the replacement, like "findOneAndUpdate's new: true is deprecated, so use returnDocument: after"
- For user-visible bug fixes, write in the form "Fix the issue where <symptom> occurs under <reproduction conditions>". Put how it was fixed at the beginning of the summary section
- For screen-related changes, indicate the scope by the name of the affected screen, not in implementation terms
- For small changes like adding one output to an existing tool, write it briefly using the existing file name or field name, without a reason. If adding a reason makes it long, move the reason to the summary section
- Write the first line of the commit message according to the same standards as above
- Match the sentence-ending tense and separators to the merged PRs and commits in that repo
Guideline 2. Start the summary section with the main purpose of the change, and end with how to verify it
- Write first what the PR fixes. It's fine to describe the situation in which the bug was noticed, but don't place it at length before the main topic. The situation description looks like the main topic and gets in the way of explaining the main topic
- For a PR that combines multiple steps composing a feature, list the steps one per line in list notation, in the order of operations or processing flow. In each line, write what is added and what becomes possible as a result. Don't split by implementation units like model, module, or file. Place details such as the contents of conditional checks or the format of records in a section after the step list
- Place the verification method at the end, writing the steps for the reviewer to check locally. Put verification already done by AI in a separate section
Guideline 3. Write so links don't break
This applies to all text displayed on GitHub, including summary sections, comments, and commit messages.
#1234Put a half-width space before and after and URLs.#1234で直したdoes not become a link.(https://example.com/日本語のページ)。は、)。is included in the URL#数字is used only for issue and PR numbers. For things with a different numbering system, such as Dependabot alerts, write the full URL.#数字will link to an unrelated issue or PR with the same number- Write the Japanese parts of URLs without percent-encoding. With an encoded URL, humans cannot read which page it links to
Principle 4. Link parent and child PRs from both sides
- In the parent PR's description, place a
## 子PRsection, and each time you create a child PR, add it in the form- #1234add in the form of - On the first line of the child PR's description, write
#1234 の子PRですwrite - Create the parent branch by stacking one empty commit on the default branch, and make it the parent PR. If there is not a single commit that is not on the default branch, you cannot create a PR
- Point child PRs at the parent branch, and make child PRs siblings. If you create the next child PR from a certain child PR's branch, the earlier PR's commits get mixed into the diff
- When asking the user where to point a PR, ask in terms of the PR relationship, not the branch name. Instead of asking "should I branch from
feature-x?", ask "should it be a child PR of #1234, or a PR pointed at main?", and add the consequence, such as when it will land in production
Principle 5. Write the squash and merge commit message by summarizing the description
When you squash and merge on GitHub, the first line of the commit message becomes the PR title, and the default body becomes the concatenation of the individual commit messages. Do not use the default body; write a summary of the description.
- Do not leave individual commit messages in the body. If you concatenate three commits, "implement A", "implement B", and "remove A", it reads as if A was implemented
- In the body, briefly write the changes and reasons that are not in the title. If the title is enough, do not write a body
- For a PR that lists the steps composing a feature in the description, write those steps in the body in the same order using list notation. Do not put details such as the contents of judgment conditions in the body
- Do not write AI attribution lines such as Co-Authored-By or Claude Session