Skip to main content

Semantic pull request

This guide explains why you need good PR titles and how you do write PR titles in Conventional Commits spec.

Why do commit messages matter?

Since the Pulsar community uses "Squash and Merge", the commit message is effectively the same as the PR title.

Engineers and writers submit or review PRs almost every day.

A PR title is a summary of your changes.

  • Vague, boring, and unclear PR titles decrease team efficiency and productivity.
  • PR titles should be engaging, easy to understand, and readable.

Good titles often bring many benefits, including but not limited to the following:

  • Speed up the review process.
    • You can tell from the title what changes the PR introduces.
  • Facilitate understanding of PR changes.
    • PR titles are shown on Pulsar release notes as items. Concise PR titles make your changes easier to understand.
    • Especially when you read commit logs in command-line tools, clear commit messages show PR changes quickly.
  • Increase search efficiency.
    • You can skim through hundreds of commits and locate desired information quickly.
  • Remind you to think about your PR.
    • If you can not write a PR title in a simple way (for example, [type], [scope], or [summary]), or you need to use several types/scopes, consider whether your PR contains too many changes across various scopes. If so, consider splitting this big PR into several small PRs. In this way, you might get your PRs reviewed faster.

How to write good PR titles?

A PR title should be structured as follows:

Semantic Pull Request Title

The rule can be interpreted as: A good title = clear format (type and scope) + self-explanatory summary.

Quick Examples

Here are some examples of unclear and good PR titles for your quick reference. Good PR titles are concise and self-explanatory since they tell you the changes in a clear and direct way.

Vague (Bad)Clear (Good)
Producer getting producer busy is removing existing producer from list[fix][broker] Active producers with the same name are no longer removed from the topic map
Forbid to read other topic's data in managedLedger layer[improve][broker] Consumers are not allowed to read data on topics to which they are not subscribed
Fix kinesis sink backoff class not found[improve][connector] xx connectors can now use the Kinesis Backoff class
K8s Function Name Length Check Allows Invalid StatefulSet[improve][function] Function name length cannot exceed 52 characters when using Kubernetes runtime

Here are steps to self-review whether the PR title is good:

  1. Select a type.
  2. Select a scope.
  3. Write a summary.

For more examples with correct formats, see Full examples.


type is "what actions do you take".

It must be one of the following.

TypeLabelWhat actions do you take?
cleanuptype/cleanupRemove unused code or doc.
improvetype/improvementSubmit enhancements that are neither new features nor bug fixes.
feattype/featureSubmit new features.
fixtype/fixSubmit bug fixes.
refactortype/refactorRestructure existing code while preserving its external behavior.
revertN/ARevert changes

Choose correct labels for your PR so that your PR will automatically go to the correct chapter in release notes. If you do not specify a type label, the PR might go to the wrong place or not be included in the release notes at all.


scope is "where do you make changes".

Scopes evolves along with development. You can check the latest valid scopes at the workflow file.


Summary is a single line that best sums up the changes made in the commit.

Follow the best practice below:

  • Keep the summary concise and descriptive.
  • Use the second person and present tense.
  • Write complete sentences rather than fragments.
  • Capitalize the first letter.
  • Limit the length to 50 characters.

Avoid some common bad cases:

  • Do not include back quotes (``).
  • Do not append period at the end.
  • Do not use GitHub keywords followed by an issue number. This information should be provided in PR descriptions or commit messages rather than in PR titles.

If you cherry-pick changes to branches, name your PR title the same as the original PR title and label your PR with cherry-pick related labels.

Full examples

As explained in the How to write good PR titles chapter: A good title = clear format (type and scope) + self-explanatory summary.

Here are some format examples. For self-explanatory summary examples, see Quick examples.

ChangesUnclear format (Bad)Clear format (Good)
Submit breaking changes[Breaking change] xxx[feat][broker]! Support xx
Submit PIP changes[PIP-198] Support xx[feat][broker] PIP-198: Support xx
Cherry pick changes[Branch-2.9] Fix xxx issue.[fix][broker][branch-2.9] Fix xxx issue
Revert changesRevert xxx[revert][broker] Revert changes about xxx
Add features
  • Adding xx feature
  • Support delete schema forcefully
  • [feat][java client] Add xx feature
  • [feat][schema] Support xx
  • Fix bugs[Issue 14633][pulsar-broker] Fixed xxx[fix][broker] Fix xxx
    Submit improvements
  • Enhances xx
  • Bump netty version to 4.1.75
  • [improve][sql] Improve xx performance
  • [improve][build] Bump Netty version to 4.1.75
  • Update testsreduce xx test flakiness[improve][test] Reduce xxx flaky tests
    Update docs
  • [Doc] add explanations for xxx
  • 2.8.3 Release Notes
  • Fix typos in xx
  • [feat][doc] Add explanations for xxx
  • [feat][doc] Add 2.8.3 release note
  • [fix][doc] Fix typos in xx
  • Update website[Website] adjust xxx[improve][site] Adjust xxx
    Update instructions/guidelinesUpdate xxx guideline[improve][doc] Update xx guidelines