Code review is an essential part of Brilliant workflow, and we need to define a strategy to make it effortless and merge requests more structured so they can be processed by automation tools such as:
- linking a merge request to a JIRA ticket
- collecting and processing commit messages
- automatically verifying code style
- automatically verifying the quality of a merge request
We described guidelines to help us create more organized merge requests, boost the code review process, and get high-quality code as a result.
Merge request best practices
- A merge request should contain all changes as you'd expect them to be. You'd be surprised how often people don't do it.
- A merge request should be mergeable into the
master branch. People sometimes ask for review, but a merge request has conflicts or requires a manual rebase.
- A merge request title should describe the change you want to make.
- If a merge request is complex and/or contains many changes, fill in a description to provide more context to a reviewer.
- Specify a JIRA ticket ID(s) in a merge request:
- Start a merge request title with the ticket ID. For example, "PRJ-123: add the Preferred badge to the hotel card."
- Or mention it in a merge request description, using the "Solves PRJ-123" or "Closes PRJ-123" syntax.
- A merge request needs to have green pipelines:
- If pipelines don't pass, the merge request can't be merged and isn't ready for a code review.
- That includes tests, linters, security checks, etc.
Code review is like writing code — everyone does it differently. But several rules make our workflow more efficient:
- Review merge requests as quickly as possible. The sooner an author of the merge request gets feedback, the sooner the merge request can be merged and shipped.
- Clarify before suggesting changes. Sometimes what you suggest may not be right. It's always better to ask questions to clarify the solution before suggesting changes.
- Every developer should complete code reviews. Even experienced developers can make a mistake. Plus, by reviewing their merge requests, new team members will learn and improve their skills faster.
- Be kind and objective. Code review is a process of giving feedback for someone's work.
- Should not be based on your subjective preferences
- Should be given in a positive manner