Have you ever been assigned a ticket with a title like “Some Images Don’t Work,” or opened a monstrous pull request containing a single commit labeled “bug fixes” as your only clue to the changes made? This level of ambiguity is frustrating and can end up costing exorbitant time and money to research. The titles, descriptions, and messages we provide in our workflow should make the jobs of not only our peers easier but also future team members who will inherit the project.
By tweaking our process just a little to document while we work, we can alleviate stress and save time and money on the project. Now don’t go breaking out the wikis and word processors just yet. Much of the critical documentation can be done within the tools you are already using. Writing actionable ticket titles, informative descriptions, and properly referencing related issues and resources can remove mountains of ambiguity and save yourself loads of time filling in the blanks or worse, making assumptions.
Before we get into the details, we need to think about the motivations behind the madness. If we’re going to spend more time writing up descriptions and details, what do we get for it? Anytime you are writing words that another person will read, think about who that person is. It might be a new developer on the team who doesn't have your background knowledge or you in a few months. Maybe a project manager, maybe a stakeholder. Will a machine be able to read and interpret this? All of these factors should influence what you write, regardless of whether it is a description of a bug or a commit message. What information will the next person need so they can eliminate assumptions about the task? Keeping this concept in mind, consider the following benefits:
- Hours of time spent onboarding a new developer could be reduced.
- Determining who signed off on a ticket and the process they followed could be done by inspecting a commit’s notes.
- Changelogs could be automatically generated in different formats for stakeholders and developers.
- Stop cursing out the previous development team because you don’t understand why they chose a particular method.
- Or worse, don’t waste your time refactoring that code, then reverting it because you finally did figure out why they chose a particular method.
- Spend time developing instead of researching a ticket.
As you’re creating a ticket, a commit message, or a pull request; remove the space for assumption. Explain why you did what you did, and, if necessary, how. Let’s start at the beginning with the ticket queue.
Tickets
In this section, we’ll focus on the most granular of issue types: tasks and bugs. Epics and user stories have their own sets of rules and fall outside the scope of this article.
Ticket titles are the first field that someone reads. As I’m looking at my queue, I should know specifically what the ticket is intended to resolve by its title. Consequently, the title should describe the action that the ticket is to fulfill. Here are a couple of examples of good and bad versions of a ticket titles.
Good: “Prevent Nav Bar From Bouncing on Scroll”
Bad: “Navigation is Wonky”
Good: “Implement Home Page Right Rail Promo Block”
Bad: “Homepage updates”
A helpful hint to consider when writing a title is that it should complete the phrase “This ticket will….” If you’ve done this correctly, the title will always begin with a verb; a call to action. When I see a ticket with the title, “Some Links are Yellow,” I think to myself, “Yes, yes they are. I’m assuming they shouldn’t be since you created a ticket, but what do you want me to do? Should all links be yellow? Or none of them? What color should they be?” Now, imagine you are a stakeholder reading over a list of completed tickets. What would you think as you read this title?
Sometimes you’re going to need more than just the title to convey the complete purpose of the ticket, so make sure your ticket descriptions eliminate any room for assumption as well. For bugs, include the steps it takes to reproduce the issue, the environment where you encountered it (OS, browser, device, etc), and what the desired result should be. For simple tasks, reference any comps that describe how it should be implemented and consider user interactions if there are any. The description field should provide extra information about the goal of the ticket.
If you are having trouble coming up with a specific enough title, consider breaking the ticket down into smaller subtasks, or promoting the ticket to an epic.
Branches
When you start your work, the best practice is to keep your main line of code clear by creating feature branches in your VCS to work on new tickets. Branches should be filterable, recognizable, and attributable. That is to say, I want to be able to locate a branch quickly by who created it, which issue it’s tied to, and what it’s about.
I prefer a format like this: "owner/issue-id/short-description"
Which could end up looking like: "keyboardcowboy/proj-1234/fix_jumping_nav"
Think about who will see the branch names: myself, other developers, maybe a project manager, the repo gatekeeper if you have one, and machines. Using this format, I can now easily find my branches to create a pull request; I can check if anyone else has a branch for this ticket number; and I can allow project software, such as Jira or GitHub, to reference this branch by searching for the issue number pattern.
Include the username, issue ID, and a brief summary in branch names to make them easily identifiable.
Commit Messages
Developers may recognize the commit message prompt as that annoying thing GIT makes you do before you can push your changes. While it may be annoying when you’re working on your own, I guarantee that coworkers and your future self will appreciate the detailed messages you provide.
The reason for the commit message is to describe the changes taking place in that commit. If you find you can’t describe everything in one sentence, try breaking the commit into smaller, atomic commits. This makes it easier to roll back isolated changes if necessary and allows you to describe each change more succinctly. Just as with the issue titles, describe what the commit does. Someone else should be able to read it and understand to a basic degree what this change encompasses.
It’s also extremely helpful to precede the commit message with the issue number. The software can recognize certain patterns in commit messages and generate links from them. Tools like PHPStorm can help automate this for your process by integrating with GIT.
Configure your IDE (PhpStorm shown) to automatically prefix your commit messages with the ticket ID.
Here’s an example of well formatted, atomic commits vs a lazy commit.
Good Commits:
[proj-1234] Refactor white space in CSS so it’s readable. [proj-1234] Remove deprecated classes and definitions from CSS and templates. [proj-1234] Increase transition timing on navigation dropdown. The nav seemed to be jumping when the user scrolled while it was open. Increasing the transition timing allows it to expand and contract more smoothly and alleviates the jumpiness. [proj-1234] Fix merge conflict in update hook number.
Bad Commits:
Nav stuff.
Notice how the third good commit has multiple lines. The other commits in this set were ancillary to the issue. The third commit is where the critical changes were made, so I explained my reasoning and why it fixes the issue. Without that, it looks like I just changed the timing. You might be able to trace the PR back to the original issue and piece things together, but a brief explanation directly in the commit can save time and headaches.
It may seem like overkill, but commits become very handy for the next developer, especially if you are using an IDE that integrates with GIT.
Many IDEs (PhpStorm shown) integrate VCS information with each line of a file. Good commit messages are like secret messages to future you or your team.
Pull Requests
Pull requests are a common method to contribute to a project without needing commit access to the repository or to the main code branch. The title of your pull request should follow the same structure as issues, but with one caveat; like tickets, they should describe the action that will occur if the code is merged, but they should also be prefixed with the issue-id of the issue they resolve. In GitHub, for example, the pattern "#ID" creates a link to that issue number. Even if you are not using GitHub as your issue manager, this is still an important reference, especially if you are running on a standard sprint cycle and need to generate reports for what was completed in each release. Humans can follow this pattern to reference tickets as well as machines.
When you merge a pull request, a commit is made against the base branch and the title of the pull request is used in the commit message. Wouldn't it be nice if you could search through all the commits between release tags, find any that are pull requests and print them with references to their original issue as a change report? It’s surprisingly simple to automate that process if you follow these guidelines. Here’s an example of a good and a bad pull request title.
Good: “[PROJ-1234] Prevent Nav Bar From Bouncing on Scroll”
Bad: “Navbar Issues”
Imagine reading this as a code reviewer or a stakeholder trying to gauge what was accomplished in the last release. Which is going to be more informative? The title text describes exactly what was addressed, and the prefixed issue number provides the information needed to create a link directly to the original issue.
Just as with the original issue, you have an area for a summary in the pull request. I’ve found the most success in separating business discussions and technical review discussions between the issue management software and the pull request tool respectively. If necessary, provide testing instructions in the proper place and that your team follows any documentation guidelines consistently.
Automated Changelogs
Stakeholders often ask us to provide a list of everything that changed in the last release. Long sprint cycles and large teams can make this a challenge, especially if your issues, commits, and pull requests are vague. The aforementioned guidelines not only make the project more understandable for people, but also for robots. On a project where the stakeholder required that an email is sent out after every release containing all the changes in that release, we used a simple, custom node script to pull all the commits made between tags and format them into a human-readable list using markdown. That list could be copied and pasted into various places, such as email and GitHub releases. I’ve found a growing number of utility programs that attempt to do this or something similar. In a single command, you have a perfectly formatted, readable changelog, complete with links to the original issues!
Here are a few helpful tools I’ve found so far:
- Drush Changelog Generator (php/drupal) - https://www.drupal.org/project/grn
- GitHub Changelog Generator (ruby) - https://github.com/skywinder/github-changelog-generator
- Our Initial Custom Changelog Generator (nodejs) - https://github.com/q0rban/changelog_builder
Documentation doesn't have to be boring and time-consuming. You can clarify your project with just a few simple refinements in your existing process and drastically reduce time spent writing up wiki documentation. Writing more detailed and informative tickets, commits, and pull requests will reduce sunk developer time, provide clarity for your stakeholders, ease your onboarding process, and provide better accountability and understanding throughout the project.
Do you have any suggestions or tips for documenting as you work? I’d love to hear about them!