In this help article, we shall outline the essential and nice to follow best practices associated with Pull requests/Merge requests in your code repository (GitHub, GitLab, Bitbucket) to extract the best out of the Cubyts platform. Please note that you can embrace these best practices over time, as you embrace the Cubyts platform.
Essential best practices:
Link PRs to Related Issues
What:
Always link your PRs to the relevant issues in your issue tracking system to create a traceable relationship between the code and the underlying requirements.
Why:
Linking PRs to issues ensures that every change is connected to a specific business or technical need, which enhances accountability and traceability.
How it helps engineering managers:
Provides a clear link between code changes and business requirements.
Facilitates better tracking of feature progress.
Improves accountability in development.
How it helps scrum masters and project managers:
Ensures that all changes are aligned with project goals.
Simplifies the process of tracking work items.
Helps in managing dependencies between tasks.
Conduct Thorough Code Reviews Before Merging
What:
Ensure that every PR undergoes a thorough code review by at least one or more qualified reviewers before merging.
Why:
Code reviews are essential for catching bugs, improving code quality, and sharing knowledge across the team. They also provide an opportunity for mentoring and improving coding standards.
How it helps engineering managers:
Improves the overall quality and maintainability of the codebase.
Facilitates knowledge sharing within the team.
Helps in identifying potential issues early.
How it helps scrum masters and project managers:
Ensures that code meets the project’s quality standards.
Reduces the likelihood of issues in production.
Supports continuous improvement in team practices.
Assign Relevant Reviewers
What:
Assign the PR to the most appropriate reviewers who have the relevant expertise and context to review the changes effectively.
Why:
Assigning the right reviewers ensures that the code is reviewed by those with the necessary knowledge, leading to more effective and insightful reviews.
How it helps engineering managers:
Ensures that the right expertise is applied to reviews.
Improves the quality of the review process.
Enhances team collaboration and knowledge sharing.
How it helps scrum masters and project managers:
Speeds up the review and approval process.
Ensures that reviews are thorough and relevant.
Facilitates better resource management within the team.
Avoid Merging PRs with Unresolved Comments
What:
Ensure that all comments raised during the review are addressed and resolved before merging the PR.
Why:
Leaving unresolved comments can introduce risks or unresolved issues into the codebase. Resolving all comments ensures that the code meets the agreed-upon standards before it is merged.
How it helps engineering managers:
Ensures that all feedback is considered and addressed.
Reduces the risk of introducing issues into production.
Maintains high code quality standards.
How it helps scrum masters and project managers:
Prevents the introduction of unresolved issues into the project.
Ensures that reviews are thorough and complete.
Supports continuous improvement in team practices.
Keep PRs Up-to-Date with the Base Branch
What:
Regularly update your PR with the latest changes from the base branch to ensure that your PR remains up-to-date and avoids conflicts.
Why:
Keeping your PR updated with the base branch prevents conflicts and ensures that the code you’re merging is compatible with the latest changes in the project.
How it helps engineering managers:
Reduces the likelihood of merge conflicts.
Ensures that the codebase remains stable and consistent.
Facilitates smoother merges and deployments.
How it helps scrum masters and project managers:
Minimizes delays caused by conflicts during the merge process.
Helps maintain a predictable and stable development process.
Enhances the reliability of release planning.
Use Feature Branches for PRs
What:
Create a dedicated feature branch for each PR, separating it from the main branch and other ongoing work.
Why:
Using feature branches keeps the main branch clean and stable, allowing for isolated development and easier management of different features or fixes.
How it helps engineering managers:
Enhances code organization and stability.
Facilitates parallel development of features.
Reduces the risk of conflicts in the main branch.
How it helps scrum masters and project managers:
Improves the management of multiple tasks and features.
Ensures that the main branch remains stable for releases.
Simplifies the process of tracking and merging changes.
Test Locally Before Opening a PR
What:
Always test your changes locally before opening a PR to ensure that they work as expected and do not introduce new issues.
Why:
Testing locally before opening a PR reduces the likelihood of issues being discovered during the review process, leading to faster and smoother reviews.
How it helps engineering managers:
Maintains a high standard of code quality.
Reduces the time spent on fixing issues during reviews.
Improves the reliability of the development process.
How it helps scrum masters and project managers:
Ensures that PRs are review-ready, reducing delays.
Enhances the efficiency of the sprint and release processes.
Supports a more predictable and stable development workflow.
Nice to follow best practices:
Write Clear and Descriptive PR Titles
What:
Create PR titles that clearly and succinctly describe the change being made, so that anyone reviewing the list of PRs can immediately understand the purpose.
Why:
A clear and descriptive title helps reviewers quickly identify the purpose of the PR, making it easier to prioritize and manage reviews. It also improves searchability and documentation.
How it helps engineering managers:
Simplifies the tracking of changes.
Facilitates easier project reporting.
Ensures clarity in the development process.
How it helps scrum masters and project managers:
Enhances visibility into ongoing work.
Aids in sprint planning and review processes.
Helps in communicating changes to stakeholders.
Provide Detailed PR Descriptions
What:
Include detailed descriptions in your PRs that explain what changes were made, why they were necessary, and how they were implemented.
Why:
A well-documented PR provides context for reviewers, making it easier to understand the changes and their impact. It also helps in future maintenance and onboarding of new team members.
How it helps engineering managers:
Ensures transparency in the development process.
Provides documentation for future reference.
Helps in assessing the impact of changes.
How it helps scrum masters and project managers:
Facilitates smoother reviews and approvals.
Enhances communication within the team.
Aids in tracking the progress of features.
Break Down Large PRs into Smaller, Atomic Changes
What:
Instead of creating large PRs, break down changes into smaller, more manageable PRs that are easier to review and test.
Why:
Smaller PRs are quicker to review, less prone to errors, and easier to merge without causing conflicts. This practice enhances the overall quality and maintainability of the codebase.
How it helps engineering managers:
Reduces the risk of introducing bugs.
Enhances code maintainability.
Speeds up the review and merge process.
How it helps scrum masters and project managers:
Improves the efficiency of sprint reviews.
Reduces the likelihood of delays due to complex merges.
Facilitates more predictable progress tracking.
Ensure PRs pass All Automated Checks
What:
Before requesting a review, ensure that your PR passes all automated checks, such as unit tests, integration tests, and linting.
Why:
Automated checks are the first line of defense against bugs and issues. Ensuring they pass before review helps maintain code quality and prevents unnecessary back-and-forth during reviews.
How it helps engineering managers:
Maintains a high standard of code quality.
Reduces the time spent on manual testing.
Improves the reliability of the codebase.
How it helps scrum masters and project managers:
Ensures that PRs are ready for review without delays.
Improves the predictability of release schedules.
Enhances the efficiency of the development process.
Use Draft PRs for Work-in-Progress
What:
When your PR is not yet ready for review but you want to share your progress or get early feedback, use the draft PR feature.
Why:
Draft PRs signal to the team that the work is ongoing and not yet ready for a full review. This practice allows for early collaboration without prematurely starting the review process.
How it helps engineering managers:
Facilitates early feedback on work-in-progress.
Helps in identifying potential issues early.
Encourages collaboration before finalization.
How it helps scrum masters and project managers:
Provides visibility into ongoing work.
Allows for early identification of blockers.
Helps in adjusting timelines and expectations.
Add Meaningful Commit Messages
What:
Write clear and meaningful commit messages that describe the changes made in each commit, providing context and reasoning for the changes.
Why:
Well-written commit messages help others understand the history and rationale behind changes, making it easier to track progress and troubleshoot issues.
How it helps engineering managers:
Improves the traceability of changes.
Facilitates better understanding of the codebase’s evolution.
Enhances the ability to audit and review the code.
How it helps scrum masters and project managers:
Aids in understanding the context of changes during reviews.
Helps in tracking the progress of specific tasks.
Supports better project documentation.
Label PRs with Appropriate Tags
What:
Use labels or tags on PRs to categorize them based on type (e.g., bug fix, feature, refactor) or priority, helping in the organization and tracking of PRs.
Why:
Labeling PRs helps in quickly identifying the nature of changes and prioritizing reviews. It also enhances reporting and filtering capabilities.
How it helps engineering managers:
Improves the organization of PRs.
Facilitates better prioritization of reviews.
Enhances visibility into the development process.
How it helps scrum masters and project managers:
Simplifies the management of the review process.
Aids in tracking the progress of specific types of changes.
Supports better sprint and release planning.
Document Breaking Changes in the PR
What:
Clearly document any breaking changes introduced in the PR, explaining the impact and any necessary steps to adapt to these changes.
Why:
Documenting breaking changes ensures that all stakeholders are aware of significant modifications that may affect other parts of the codebase or dependent systems.
How it helps engineering managers:
Prevents unexpected disruptions in the codebase.
Facilitates smoother integration and deployment processes.
Ensures that necessary preparations are made for breaking changes.
How it helps scrum masters and project managers:
Helps in planning for potential impacts on timelines.
Ensures that the team is prepared for changes.
Enhances communication with stakeholders regarding the impact of changes.
Resolve Conflicts Before Requesting a Review
What:
Resolve any merge conflicts in your PR before requesting a review, ensuring that the PR is ready for smooth merging.
Why:
Resolving conflicts before review prevents delays and ensures that reviewers can focus on the code changes rather than on conflict resolution.
How it helps engineering managers:
Speeds up the review and merge process.
Reduces the likelihood of errors during merging.
Ensures a smoother integration into the codebase.
How it helps scrum masters and project managers:
Minimizes disruptions to the review process.
Helps maintain a steady and predictable workflow.
Supports timely and efficient sprint execution.
Include Screenshots or Demos for UI/UX Changes
What:
When making UI/UX changes, include screenshots or demo videos in the PR to visually demonstrate the changes made.
Why:
Providing visual evidence of UI/UX changes helps reviewers understand the impact of the changes and ensures that the design is implemented as intended.
How it helps engineering managers:
Ensures that UI/UX changes meet design standards.
Facilitates better communication with designers.
Reduces the likelihood of design-related issues in production.
How it helps scrum masters and project managers:
Enhances the clarity of what has been changed.
Supports more effective reviews of visual changes.
Helps in communicating changes to stakeholders.
Follow Project-Specific PR Guidelines
What:
Adhere to any specific PR guidelines established for your project, such as coding standards, branch naming conventions, or review protocols.
Why:
Following project-specific guidelines ensures consistency across the codebase and simplifies the review and merge process.
How it helps engineering managers:
Maintains consistency and quality across the project.
Simplifies the onboarding of new team members.
Reduces the likelihood of errors and misunderstandings.
How it helps scrum masters and project managers:
Ensures that PRs align with project goals and standards.
Simplifies the management of the review process.
Supports the overall organization and efficiency of the project.
Regularly Update PR Descriptions with New Information
What:
As your PR evolves, update the description with any new information, changes, or decisions that are made during the development process.
Why:
Keeping the PR description up-to-date ensures that all reviewers have the latest context, making the review process more efficient and informed.
How it helps engineering managers:
Ensures transparency in the development process.
Facilitates better communication and decision-making.
Enhances the quality and accuracy of reviews.
How it helps scrum masters and project managers:
Provides up-to-date information for tracking progress.
Supports more accurate and informed reviews.
Helps in adjusting plans based on the latest information.
Close Stale PRs Timely
What:
Regularly review and close any stale PRs that are no longer active or relevant to keep the project clean and focused.
Why:
Closing stale PRs helps maintain a clean and organized project, reducing clutter and ensuring that the team focuses on active work.
How it helps engineering managers:
Keeps the project repository organized.
Reduces distractions from outdated or irrelevant PRs.
Ensures that the team’s focus is on active and priority work.
How it helps scrum masters and project managers:
Helps in maintaining a clear and focused backlog.
Ensures that only relevant work is tracked and reviewed.
Supports better project management and reporting.