Pull Requests and Ticket Management Best Practices
This article is for those who value a production work environment and understand the importance of reducing misunderstandings in a team and between them. Using best practices when creating tickets for tasks and opening PRs, we aim to help you develop the skills and knowledge necessary to work with others effectively. So, as you read on, remember that the most important takeaway from this article is how to use these tools with confidence, ensuring that your collaborative efforts contribute to the success of your team and the overall improvement of your work environment.
What are tickets, pull requests, and what are their advantages?
In software development and project management, “tickets” and “pull requests” (PRs) are vital components to streamline and enhance the development process.
A ticket is a concise and documented record of a task, issue, or enhancement that needs to be addressed within a project. Tickets are often created within ticket management systems like Jira and are assigned to individuals or teams responsible for resolving them. They help track and prioritize work, ensuring that nothing falls through the cracks. By using tickets, you can improve organization, accountability, and visibility into a project’s progress, making teamwork and project management more efficient.
A pull request is a fundamental tool in git hosting services like github. It is a request made by a developer to merge their changes, for example, from a feature branch into the main codebase or a different target branch. Pull requests are essential for code review and quality control. They enable collaborative code review, allowing team members to provide feedback, catch potential issues, and ensure that the code changes meet the project’s standards. This collaborative approach to code integration helps ensure code quality, minimizes errors, and leads to a more robust and maintained codebase.
To summarize, both tickets and pull requests are integral to effective project management and software development. Tickets help in task organization and accountability, while pull requests facilitate collaborative code review and quality assurance, contributing to smoother and more efficient team workflows.
Best practices for working with tickets
Creating and working with tickets effectively is crucial for efficient project management and collaboration. Here are some best practices to consider:
- Before opening a ticket for a bug, check that it hasn’t already been opened.
Search through existing bugs to see if any match what you’re about to report. If you do find said ticket, add a comment describing any additional information you can: different context or environment, how to reproduce, new images or GIFs.
2. Write clear and concise tickets.
When a ticket is unclear it can cause a misunderstanding between the person working on the ticket and the person requesting the work. This leads to wasted effort trying to understand what is being asked, and in some cases, the work done may not be what was actually requested. Some tips for writing clear and concise tickets:
– Be specific about what you expect the result to be.
– Include all relevant information
– Avoid using jargon
– Use clear and concise language
– If possible, include screenshots, videos, or GIFs
3. Add the right amount of detail
When writing the ticket, you may want to write as many details as possible to make sure no stone is left unturned, but too many details can be overwhelming for the assignee. Try to put yourself in their shoes and adopt their perspective. When they see the ticket they might not even have all the information and context needed to start. If not enough information is given, the assignee may ask for further clarification, which can slow down development. The best way to get that golden balance is to include enough detail so that the assignee can understand the task or problem and have enough information to deliver.
4. Include screenshots, videos, or GIFs when necessary
A picture is worth a thousand words. That’s especially true when it comes to technical issues. By including screenshots, videos, or GIFs you can save yourself a lot of trouble. Visual aid helps the person resolving the ticket understand the problem more quickly and come up with a solution more efficiently.
5. Link issues when necessary
When you create a ticket for your task, take a second to see if it relates to an already existing ticket. This surfaces important relationships and prioritization, the most important relationship between tickets is the “is blocked by/blocks” relationship.
6. Use User Stories for larger tasks
For large and complex tasks that cannot be easily managed as individual tickets, consider using user stories. User stories help capture high-level requirements, which can then be broken down into smaller actionable tasks. Once a user story is created, break it down into smaller, well-defined tasks or subtasks that can be assigned. This approach allows for a more granular and manageable approach to handling complex work items, ensuring that progress can be tracked effectively at both the user story and task levels.
7. Integration with Other Tools:
Consider integrating your ticket management system with other 3rd party tools such as a messaging platform like Slack, a version control system like Gitlab or Bitbucket, or a CI/CD system like Jenkins. Integration with a messaging platform will allow team members to receive real-time notifications about ticket updates, new assignments, or important changes. Integrating with version control systems allows for seamless tracking of code changes and their association with specific tickets, simplifying the connection between code development and task completion. Finally, integration with CI/CD systems like Jenkins allows for an automated approach to managing code changes linked to tickets. Through CI/CD pipelines that trigger code changes, the code is thoroughly tested and validated, and reporting the status of the build on the ticket will provide the connection between the jobs run and the ticket.
Best practices for opening a pull request (PR)
Opening a pull request (PR) is a critical step in the collaborative software development process. Here are some best practices to consider when opening a PR:
- Small number of Lines of code (LOC)
A study of a Cisco Systems programming team revealed that developers should only review a maximum of 200-400 LOC over 60 to 90 minutes should yield 70-90% defect discovery. Beyond 400 LOC the ability to find defects diminishes. - Title and description
Context is essential for understanding and reviewing a PR. Reviewers must know what the problem is before they can understand if it’s been resolved. That’s why you should care about the title and description to provide an overview of why the work is taking place. It also helps to provide a link to the ticket assigned for this task. - Simplify commit messages
When first working on a project, a developer will create a local clone of a repository, make changes in a side branch, push the changes to the origin, and then raise a pull request to merge the code in the main repository.
A best practice for writing commit messages is to prefer brevity over verbosity. The title should be treated like an email subject. Also, adhere to writing sentences in imperative i.e., ‘add run tests stage,’ not ‘adds test stage’ or ‘added run tests stage’. This rules out confusion for reviewers, as declarative sentences often mean the work is done. Also, using imperative statements helps in quick code rollbacks, if needed. - Resolve disagreements through direct communication
Instead of waiting for a reply, try initiating direct communication through a messaging platform like Slack or one-to-one as soon as the conversation starts. Direct communication will be much more helpful since:
– Feedback will be faster
– Verbal communication leads to fewer misunderstandings
– Verbal communication is a much more thorough review than sending messages back and forth
– Direct conversion prevents constant context-switching - Don’t skip timely reviews
Many developers, even seniors, fail to do a proper code review. Occasionally, developers will approve and merge their code in an effort to complete tasks and prevent getting blocked by a pending code review. To prevent such issues, high-performing development teams follow these practices:
– Ensure the code is reviewed within a few hours. The quicker the feedback from the reviewer, the better. As the task is still fresh for the developer.
– Sometimes, a review will turn into a discussion over the best way to do a feature or bugfix in the comments. This way is an opportunity to learn something new, but it might annoy others who need to work on the task and are forced to read the comments.
– As a precaution, if you do not have the time to calmly review a pull request, do not accept review requests.
The effectiveness of project management and code integration can make all the difference in software development. By following the best practices discussed in this article, from well-structured tickets with clear descriptions to integrated with systems to provide visibility of our progress to opening small meaningful pull requests, we give our teams the tools to work together seamlessly, reduce misunderstandings, and maintain the highest standard of code quality. These practices enhance our work environment and help set us up for success in our projects. So let’s continue striving to build a culture of efficiency and grow as collaborative and efficient teams.