Context and Problem Statement
As a team, we have previously been inconsistent in how we write titles for pull requests. Most team members put the Jira issue identifier(s) in the title to help the Jira/GitHub integration recognize the relationship between the pull request and the relevant issue(s). However, even that aspect of the title is not written in the same way by the whole team.
If we had consistent formatting of pull request titles, we could automate more tasks related to TestFlight builds. That would bring us a bit closer to having a fully automated process for making TestFlight builds.
Decision Drivers
- Improve automation associated with making TestFlight builds
- Ensure proper interaction between Jira and GitHub
Decision Outcome
Pull request titles for a single Jira issue will take the following form:
[IOS-####] Meaningful description of the changes
Pull request titles for multiple Jira issues will take the following form:
[IOS-####, IOS-####] Meaningful description of the changes
The important part is enclosing the Jira issue number(s) in square brackets. This enables automated examination of Git commit history to extract Jira issue numbers for merged pull requests. That, in turn, makes it much easier to generate a report of what has changed between two TestFlight builds.
The “meaningful description” should be short, typically one sentence. Incomplete sentences are fine. It is a title for the work, and following general title conventions of American English ought to be sufficient. This text is shown in the list of open pull requests today. Someday, it may also be used as part of generating release notes automatically for individual TestFlight builds.
Considered Options
Putting the Jira issue number(s) in the title is a critical aspect of how Jira determines that a given pull request is associated with one or more issues. The following options were considered for how to put this into the title:
IOS-#### Meaningful summary of changesIOS-####: Meaningful summary of changesIOS-#### - Meaningful summary of changes
Ultimately, enclosing the issue number(s) in square brackets makes extraction of Jira issue references very straightforward. The other options have too much ambiguity to be reliable.