Rules to Better GitHub - 43 Rules
GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere.
Here is a series of rules on how to get the most out of GitHub.
Learn more about Scrum with GitHub.
Everybody strives to be perfect, but mistakes are normal, and it is easy for a developer to skim over errors when they've read their own code code hundreds of times!
Pull requests are the best way to ensure that two sets of eyes see every change - so the responsibility is never solely on the person writing the code.
When Pull Requests are enabled, developers must create a branch and make their changes on that branch. Then they submit a Pull Request to merge their changes back into main. Each pull request must be approved by another reviewer.
Useful resources - learn about Pull Requests
Video: What is a Pull Request? (3 min)Consistent naming is important so that users of your GitHub account can easily find what they are looking for and so that you appear professional.
Adding a description to your repositories is essential, so they do not appear blank in the preview on your GitHub profile.
It is important when working in multiple projects to ensure consistent practices.
Structuring your repositories consistently makes your project feel professional, and makes it easier to work with as it is predictable.
It is important that you, especially a developer, knows how to use labels for GitHub issues when using an open source project on GitHub, as it would help compact issues and make the issue management workflow more efficient. Essentially, having such a predictable workflow will let the community feel professional.
Every new repository comes in with some default labels out of the box that you could use to label your issues to help create a standard workflow in a repository. A list of the default labels and their general uses can be found here: GitHub - Managing Labels
Depend on projects, there often need to be new labels created on top of the default labels. For instance, when you are using an internal project management solution (such as Azure DevOps) for an open source project, a new label "added to backlog" is created and applied to applicable issues specifically for demonstrating that an issue has been added to the Azure DevOps backlog and is being worked on for the community. This way you can give the community an understanding of the current goals of the project and a higher feeling of interactivity with your development team.
Bad Example: It is hard to understand what issues are being worked on
Good Example: It is very simple to understand if an issue has received attention
GitHub Issues offer a great way of raising Issues within projects. However, it can be difficult to distinguish whether the Issue is a bug, feature request or just a question. GitHub Issue Templates should be used to help standardize Issues and ensure they have enough information for a developer to start work.
Let's take a look at how implementing Issue Templates can improve repository backlogs...
For instructions on setting this up:
Some websites use GitHub to manage their content (e.g. SSW Rules). GitHub makes reviewing changes easy through "Pull Requests".
A Pull Request is a request to make changes to 1 or more files. GitHub provides out of the box functionality for reviewing changes in a pull request. This process is as follows:
- Open the Pull Request
-
Examine the changes using the tabs:
- Conversations: Comments people have made about the change
- Commits: Summary of the changes the requester has made
- Checks: You can ignore this if you are not a developer
- Important - Files changed: See the difference between the old and new files being changed. Red highlighting indicates deleted parts and green highlighting indicates added parts.
This visual preview of the changes to a markdown file is accessed via Files changed | Display the rich diff
-
Approve OR ask for changes
a. Go to Files changed | Review changes
b. Select an option:- Choose "Approve" to mark it as ready to go live
Add a comment with feedback (if necessary) - Choose "Comment" for general feedback when PR it's not ready for approval
- Choose "Request changes" for mandatory changes to the PR
c. Press "Submit review" so that the requester can see it
- Choose "Approve" to mark it as ready to go live
- Done - your review has been submitted ⭐
As a software developer, you are going to create Pull Requests (PRs) that you want to be easy for others to review and approve. The quality of a Pull Request can vary - from cryptic to well-written.
Including a little bit of context helps your reviewer understand changes quickly so they can review your PR faster and give better suggestions.
There are 2 easy things you can do to improve your Pull Request:
1. Write a concise and self-explanatory title
The key to writing a concise Pull Request is to base the PR itself on a PBI / issue.
Good titles cover:
- What the Pull Request will do
- How the Pull Request achieved it
- Emojis! Follow the GitMoji.dev standard
Examples:
PBI title: Product Backlog Item 100359: "Desktop App | Exporting occasionally failed"
Pull Request title: Fix exporting
Bad example - Pull Request title does not tell what issues have been fixed and how
Pull Request title: 🐛 BUG - Fix desktop app exporting - prevent database concurrent access while exporting
Good example - Pull Request title briefly describes the fix that it has
Having the "What" information allows the reviewers to quickly understand what this is about while having the "How" can help the reviewer to quickly understand how your PR solved the problem. Sometimes we might want to put the "How" in the PR body if it is too long or hard to explain in one sentence.
2. Write a clear and concise description
The Pull Request description is a medium for the developer to tell the reviewers what the changes are about.
Tip: For straight-forward changes the self-explanatory title might be enough. You should still include context so the reviewer knows what initiated the changes (examples below)
Good descriptions cover:
-
Context:
- Relates to #{{ ISSUE NUMBER or URL}} (⚠️ see avoid linking any Issues that you do not want to close)
- From email: {{ SUBJECT }} (like the rule Warn then call)
- As per my conversation with {{ NAME }} (like the rule Do you send as per our conversation emails)
- I noticed a problem: {{ DESCRIBE }}
Linking the source to a PR serves as documentation on which development work that was done. It helps in the future to debug when and which changes were introduced and the original specification of that piece of work.
Tip: If you noticed that a change needed to be made and had no specific task/issue, use 'I noticed...' from above.
- Pair or mob programming?
As per Do you use Co-Creation Patterns?. E.g. "Worked with @bob, @mary and @jane"
- What the PR is about and why you raised it
- How the PR will achieve the feature / fix the bug / other goals
- Screenshots / Done Videos to help the reviewer to understand the changes. E.g. Styling changes
- Tell reviewers if there is an area you are uncertain about. E.g. "I'm looking for feedback on this code"
PR title: Update Rule “meaningful-pbi-titles/rule”
PR description:
Figure: Bad example - Cannot tell what was done here
PR title: Update Rule “meaningful-pbi-titles/rule”
PR description: Added missing video caption + removed unnecessary brackets
Figure: OK example - Clear and concise description, however it's not clear what task triggered the change
PR title: Update Rule “meaningful-pbi-titles/rule”
PR description: From email, subject: SSW.Rules - Video caption missing Added missing video caption + removed unnecessary brackets
Figure: Good example - It's clear what changes are being made and where the task came from
There is also well-known Pull Request semantics like Conventional Commits on how to write a PR body, but we can still have a great PR without using such preciseness.
How to approach making a Pull Request
Video: 5 Tips For Better Pull Requests (11 min)
FAQs
Q: Are you making many small changes?
A: You should summarize by saying: “Improved readability” OR “Fixed typos and grammar”.
Q: Are the changes big and complex?
A: You should include a demonstration of the change.
E.g. A screenshot to show text/UI changes, or a Done video to demo functionality changes.Q: Are you using a CMS editor (like Netlify or Tina)
A: CMS editors may automatically add a placeholder description. If you're using a CMS to make your changes, you may need to go to the PR afterward and update the description to include the context.
Tip: Ensure devs follow these tips by using a template. Learn more and check out a template example.
The use of Draft Pull Requests is a handy practice to indicate work in progress promoting early collaboration and continuous feedback.This approach enhances code quality, reduces duplication, and helps to maintain a transparent and efficient development pipeline. Creating Draft Pull Requests will also trigger GitHub Workflows so developers get early feedback on the quality of their changes.
Draft Pull Requests are less effective if they are not clearly marked as Draft, as is the case on GitHub. To make them clearer, use a naming convention like
🚧 WIP: {{PR Title}}
to clearly show that it is a Draft Pull Request.GitHub
If you want to go one step further, you can add the WIP App to your repo. The WIP App prevents the merging of Pull Requests with "WIP" in their title. When you are ready to go, you just remove the WIP prefix.
Azure DevOps
The best way to handle continuous development and deployment is following GitHub Flow. The basic idea is to always deploy from master , and to create a feature branch for every feature. When the feature is complete, it is merged back to master via a pull request, which provides a trigger for other developers to build.
Using this strategy, master is always production-ready and deployable.
Note: This rule applies to git. For branching advice in TFVC, see when to branch.
The process
Assumption
Set up build system to deploy from the master branch
Your build systems should always deploy from master, and should automatically deploy on every commit to master.
Since master is always being deployed, it must always be in a deployable state.Step 1 - Create a branch
a) Create a "feature branch" for every PBI
When starting a PBI from the task board, create a branch from master with a descriptive name for that feature.
git branch start-stuff
Figure: Bad example - Branch name is not descriptive
git branch create-basic-web-application
Figure: Good example - Branch name describes the intent of the change
It is critical that this branch always comes off master, not another feature branch. Master is the only branch that is mandated to be in a deployable state, so any other option is unsafe.
Obviously, we're creating a lot of branches and merging a lot under this strategy - and that's ok. Be sure to keep your PBIs small (as per breaking large tasks into smaller tasks), and you will not have much merge pain.
The benefit of creating feature branches is to reduce the number of conflicts and churn of unfinished code during development of a feature. It allows features to be developed independently of each other and reduces the amount of expensive "pull latest from the server, and rebuild everything" operations, as well as greatly limiting the impact of commits with unfinished code.
b) Code away and complete the PBI
c) Create a commit - it will contain your changed files on your local PC
While working, commit frequently to this branch with nice, descriptive messages. For example: "Added a field to hold the product category to our timesheet read model" or "added a column to the timesheet summary UI for the product category".
git commit -m "Started report change"
Figure: Bad example - Commit message does not describe what was changed
git commit -m "Added a product category filter to the timesheet summary report UI"
Figure: Good example - Commit message describes exactly what was changed
d) Push your changes to your remote Feature Branch
Step 2 - Open a pull request (to merge from your current branch to the master)
When the change is complete, or when you want feedback on anything, open a pull request to merge the branch back to master. The pull request is more than just a request to merge, it is a request to have someone review the code and architecture, or image and to discuss any issues. Resolve these issues with more commits in the branch before continuing.
Tip: A best practice is to have another developer review your work and then approve.
It is easy to chalk this step up as busy-work, but it is one of the most valuable parts of the strategy.
Assumption
Deploy the changes to a staging environment. This allows the features to be tested before being merged to master.
Some prefer to move this step to after the merge, especially when using a release management tool like VSTS Release or Octopus Deploy (see Do you use the best deployment tool). If you decide to go this route, remember that master should remain deployable and production ready at all times and that all branches come from master. If skipping this step, ensure that you have CI on your feature branch to ensure that your branch compiles and passes all tests before merging.
Step 3 - Merge and Deploy (to master)
Once everyone is happy and everything is tested, complete the pull request, which will merge back to master. Ensure you are not using the "Fast Forward" merge option (git), or details about the branch will be lost - it will appear as though all work was done in master. Being able to see the feature branches in the git log is very useful.
After you completed the pull request, make sure you also delete the branch that you made the pull request of. Deleting your completed branch will not just help yourself in the long run, but also everyone else. Having too many branches especially a stale one will confuse developers on what "may" be in progress, moreover it would cause so much pain to the future developer when they have to do a clean-up and the branch author has left.
Otherwise, you can do it before you complete the pull request by ticking delete branch option.
Once merged, master should immediately and automatically be deployed (in a perfect world, to production).
Reviews are a crucial step in the PR process, as they ensure that the code/content is of high quality and adheres to the standards of the project. However, sometimes, developers encounter minor changes that do not require extensive reviews. In such cases, using a rubber stamp label can help expedite the PR approval process.
The rubber stamp label signifies that the change can be approved without extensive scrutiny. It is typically used for minor changes such as typos, formatting issues, or small documentation updates. By using a rubber stamp label, we can save time on reviews.
To use a rubber stamp label effectively, you must follow some best practices:
- Only use the rubber stamp label for minor changes - As mentioned earlier, the rubber stamp label is meant for minor changes only. Developers must ensure that the changes they make are truly minor and do not require in-depth reviews.
- Ensure that the change adheres to other standards - Even though the change is minor, it must still follow the project standards. Developers must ensure that their changes do not introduce any new issues or errors.
By following these best practices, developers can use the rubber stamp label to get their PRs approved quickly without compromising the quality of the project.
Here are the steps to use the rubber stamp label effectively:
- Make the change and submit a PR
- Clearly describe the changes
- Add the rubber stamp label to the PR. This means that the change can be approved without detailed review
- Wait for the PR to be approved, hopefully in less time than other PRs... it will clearly show the label to reviewers
- Once the PR is approved, the changes will be merged into the codebase
Pull requests are a fundamental feature of collaborative software development, allowing contributors to propose changes to a project and receive feedback from other developers. When reviewing a pull request, it can be tempting to make additional changes beyond those requested by the PR creator.
Certain projects (E.g. SSW.Rules) allow these additional edits, without the need for extra reviews by someone else. Knowing that, it's crucial to make sure the changes are correct, necessary and beneficial to the project before adding them.
Most common scenarios where editing an existing PR is encouraged:
- Fixing typos
- Grammar improvements
- Formatting (Markdown) fixes/improvements
For the cases where your wanted change can serve as a learning opportunity to others, it is always best if you ask them to action by requesting a change. This way the extra change can be avoided in the future.
Warning: Only experts should include their own changes to an existing PR.
Never add extra changes to a PR if you are less experienced or unfamiliar with the project. The additional changes may be unnecessary or even harmful!Ultimately, the decision to add additional changes to a pull request should be made based on the needs of the project and the expertise of the contributors involved. It's important to carefully consider the impact of any additional changes and ensure that they are aligned with the project standards.
Written communication can easily cause misunderstandings. Help the reader understand your message better by:
- Using “>” and indentation when quoting the text from others, like the original email you are replying to, or a web page, etc.
- Your new text should be kept to the left
- Add numbers if the sender didn't and it is appropriate
This way you won't forget any questions in the original email.
Note: You do not need to use ">" and indentation, when you are replying to the task that is very clear, because in this case extra text reduces clarity.
To: Adam Subject: RE: Change on Northwind app Figure: Bad example - There's too much information with no reasonable order
To: Adam Subject: RE: Change on Northwind app Figure: Bad example - Even with order, without spacing the text becomes cramped and hard to read.