Secret ingredients to quality software

SSW Foursquare

Rules to Better GitHub - 22 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.

  1. Pull requests make others know about changes you've pushed to a repository. Once a pull request is sent, people can review changes, discuss potential alterations, and even push follow-up commits, if necessary.

    github pullrequest bad 2
    Figure: Bad example - Every developer commits to the master branch, code is not reviewed, and code quality is poor

    github pullrequest bad
    Figure: Bad example - Use the out of the box pull requests to ensure all code is reviewed

    github pullrequest 1
    Figure: Good example - Use the plugin "Reviewable". Reviewable improves pull requests and code reviews with a powerful UI and easy code commenting. See the Reviewable icon above

    github pullrequest 2
    Figure: See how easy it is to see the code rejected

    Useful resources - learn about Pull Requests

  2. Do you know how to name a GitHub Repository?

    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.

    name github bad
    Figure: Bad example – Repository names are not consistently formatted

    name github ok
    Figure: OK example – Repositories are following the lower-cased hyphenated format that is common for open source projects

    name github good
    Figure: Good example – Repository names are name-spaced in the format [CompanyName].[ProjectName]

  3. It is important to add a description to your repositories so they do not appear blank in the preview on your GitHub profile.

    bad no description
    Figure: Repositorties with no description look bad

    good nice description
    Figure: Repositorties with a description look good

  4. 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.

    As per Do you make awesome documentation?:

    structure github bad
    Figure: Bad example – The folder containing the source code is called ‘trunk’ rather than ‘src’ + there is no 'docs' folder containing the important documents

    structure github good
    Figure: Good example - All documentation is in the ‘docs’ folder, samples are in the ‘samples’ folder, and all the source code is under ‘src’

  5. 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. issues bad example

    Bad Example: It is hard to understand what issues are being worked on

    issues good example

    Good Example: It is very simple to understand if an issue has received attention

  6. Do you use GitHub Topics?

    Topics are a great way to classify your repositories on GitHub.

    Topics are free text tags that help identify the technologies, purpose, and intent of your project.

    Adding topics can increase the discoverability of your repos for both bots and human searchers.

    GitHub introduced topics in 2017, and you can use topics to search for repositories. For example, if you are looking for Blazor examples or libraries, you can enter Blazor as a search term, and then refine the search to repositories that have been tagged with the ‘Blazor’ topic.

    github repositories topics search
    Figure: Searching for repositories by topic

    Topics also help others to find your repository and increase the visibility and discoverability of your work.

    github repositories topics bad
    Figure: Bad Example – no repositories tagged with topics on the first page

    github repositories topics good
    Figure: Great example – every repository is meticulously tagged with topics

  7. When you have a public project in GitHub you have some graphs available that give you some statistics helping you to understand who is using your project and why they are using it. These graphs can be found under the Insights tab.

    view project 1
    Figure: Under your project name, click Insights

    Read more about the project’s graphs: https://help.github.com/en/github/visualizing-repository-data-with-graphs/about-repository-graphs

    Some project graphs available:

    Pulse Graph

    view project 2
    Figure: Pulse graph shows a summary of the project activity

    Read more about Pulse Graph : https://help.github.com/en/github/visualizing-repository-data-with-graphs/viewing-a-summary-of-repository-activity

    Contributors Graph

    view project 3
    Figure: Contributors graphs show the top 100 contributors to the project

    Read more about Contributors Graph : https://help.github.com/en/github/visualizing-repository-data-with-graphs/viewing-a-projects-contributors

    Traffic Graph

    view project 1
    Figure: Traffic graphs show the project’s traffic, including clones, visitors in the past 14 days, referring sites and popular content to anyone with push access to the project

    Read more about Traffic Graph : https://help.github.com/en/github/visualizing-repository-data-with-graphs/viewing-traffic-to-a-repository

  8. Do you know how to write a good pull request?

    As a software developer, it is very common to see a pull request. The quality of a pull request can vary - sometimes we have to deal with a cryptic pull request and sometimes we find a very well written pull request.

    Having a great pull request message can help your peers to understand your pull request quickly so they can review your pull request faster and also give you better suggestions.

    While the pull request itself is valid and may offer a high value, you need to spend a bit of time to understand what is the context of this pull request and what does it change. Doing this step can take your time easily from 1 minute (if you just recently touched the code) to more than 10 minutes (if it has been a long time since you worked on it - or even if you have never touched the code).

    Writing a great pull request can help your peers to understand your code better and therefore, they can give you better insights (or faster review turnaround time, that's great!).

    There are a couple of things that you can do to improve your pull request:

    1. Write a concise and self-explanatory title
    2. Write a concise and descriptive body
    3. Link the pull request to the associated issues / PBIs

    1. Write a concise and self-explanatory title

    The key to writing a concise pull request is to base the pull request itself on a PBI / issue.

    Example 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: "Fix desktop app exporting - prevent database concurrent access while exporting"

    Good example - Pull request title briefly describe the fix that it has

    The important information in the title are:

    1. What the pull request will do
    2. How the pull request achieved it

    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 pull request solved the problem. Sometimes we might want to put the "How" in the pull request body if it is too long or hard to explain in one sentence.

    2. Write a concise and descriptive body

    Pull request body is a medium for the developer to tell the reviewers what the pull request is about. Things that need to be kept in mind before writing a pull request body:

    1. What the pull request is about and why did you raise a pull request
    2. How did the pull request will achieve the feature/fix the bug/other goals it may have
    3. (Optional) Put a screenshot if it will help the reviewer to understand the changes (e.g. front-end cosmetic change)
    4. (Optional) What do you want the reviewers to do - this can be approvals (most of the case) or looking to get more feedback on a piece of code in the pull request.

    better pr bad pr
    Bad example - Pull request with vague title and no description

    better pr good pr
    Good example - Pull request with a good title and descriptive body

    There is also a well-known pull request semantic like Conventional Commits on how to write a pull request body, but we can still have a great pull request without using such semantic.

    Since we already have a great title and body, the last thing to do is to associate this pull request to the related PBIs or issues.

    Linking an issue to a pull request can serve as documentation on which development work that was done on a specific PBI/issue. It may help the team in the future to debug when and which changes were introduced and what was the original specification of that piece of work.

    better pr link issues
    Figure: Linking a pull request to the related issue

    better pr link issues linked
    Figure: A pull request is now associated with the related issue

  9. 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:

    1. Open the Pull Request
    2. 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

    Figure: Reviewing tabs in a GitHub Pull Request

    Figure: The view via "Display the rich diff" button

    1. 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

    Figure: Steps for submitting a Pull Request review

    1. Done - your review has been submitted ⭐
  10. Do you use indentation for readability?

    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.

    Figure: Bad Example - there's too much information here

    Figure: Good Example - You can clearly see the context of each part of the reply

    Note:

    • When using Outlook, the raw “>” character may be automatically formatted to a “>” bullet point. This change is a problem because it may change to a normal bullet point after being sent. To prevent this issue, press Control+Z to turn it back into the raw “>” character.
    • For those using mobile devices the indentation function is not available, try instead using 3 spaces to indent manually.

    GitHub

    When using GitHub, you can use 4 spaces to indent a task and get clear separation between task and response. You can also use a ">" symbol to achieve a similar result.

    githubindentwrite
    Figure: How to write indentations with GitHub in Markdown

    githubindentpreview
    Figure: Preview of different ways to add indentations in GitHub

    You can find more info about GitHub syntax at Basic writing and formatting syntax.


    Video: Top 10+ Rules to Better Email Communication with Ulysses Maclaren

    Note: Some people also use a different text color in their reply, but this is generally overkill

  11. It is important when creating a new repository, to set it up correctly. Repositories without Descriptions, ReadMe files or licenses do not appear professionally built.

    create repository bad
    Figure: Bad Example – Without the correct .gitIgnore, files that should not be included in the repository will be added. Without the correct license, your project will either be under-protected or over-protected

    create repository good
    Figure: Good Example – As well as a good repository name and description, a ReadMe, .gitignore and license will be included in the repository.

  12. Reading ugly commits is not very pleasant and makes it very confusing when you have to check the commit history.

    2020 09 17 17 19 04
    Bad Example: The commits have no meaning

    Ways to improve your commit log:

    Tip #1: Have a nice, concise comment

    Examples:

    • "Fixed bug with emoji engine"
    • "Added new emoji filter"
    • "Updated Architecture Diagram to have emojis"

    Tip #2: Using prefixes

    Even better is to add a helpful prefix to categorize your commits.

    Examples:

    • "Fix: Fixed bug with emoji engine"
    • "Feature: Added new emoji filter"
    • "Doc: Updated Architecture Diagram to have emojis"

    Tip #3: Using emojis 💄

    In a text message, emojis helps to add emotion and context to plain text. Why not use them in commit messages too 😃?

    Examples:

    • "🐛 Fixed emoji engine in language component"
    • "🚀 Added emoji filter on Snapchat"
    • "📄 Added emoji’s to changelog"

    There are a bunch more options to choose from - carloscuesta/gitmoji: An emoji guide for your commit messages. 😜 (github.com)

    Tip #4: Using gitmoji VSCode extension

    Gitmoji - Visual Studio Marketplace (visualstudio.com).

    You can even go 🤘 hardcore and use the gitmoji cli - carloscuesta/gitmoji-cli: A gitmoji interactive command line tool for using emojis on commits. 💻 (github.com)

    commits with emojis
    Good Example: Great use of emoji and concise message

    See what emojis work best with each topic here: https://gitmoji.dev/

    emojis list
    Figure: Emojis list

  13. If a Product Owner sends an email to the development team with a request, that email should be turned into a Github Issue before any work is started or the work is prioritized on the backlog.

    Power Automate has a connector to do this automatically when an email arrives in Outlook. It can create a new Github Issue by parsing the From, To, Subject and body of the email.

    However, at the moment there is a limitation that it doesn't read inline attachments in emails and therefore you have to create your issues manually in Github.

    email to github issue2
    Figure: Power Automate | Connectors | Github

    email to github issue1
    Figure: Configure Flow connectors to create a new Github Issue from Outlook

    🔥 Warning: This Flow connector does not suport inline images.

    email to github issue3
    Figure: Good Example - Github issue created from Outlook using Flow connectors

    email to github issue
    Figure: Bad Example - Github issue created using Flow - inline attachment shows up as junk characters

  14. If all members use 2FA in your organisation, the risk of unauthorised access to your repositories is lower. GitHub organisations can be configured to require all members to use 2FA to join.

    1. Go to your organisation | Settings | Organization security
    2. Under 'Two-factor authentication', select 'Require two-factor authentication for everyone in your organization'
    3. Save

    require2FA
    Figure: Require 2FA in your organisation

    Enforcing 2FA in an existing organisation will remove members that are not using 2FA.

    See the GitHub docs Requiring two-factor authentication in your organization

  15. Do you restrict repository deletion?

    When deleting GitHub repositories, it can be hard to tell if you are on a fork or the base repository as the interface is very similar. This can lead to accidental deletions of base repositories.

    To avoid this, the organisation owners should be the only members allowed to delete repositories. Follow these instructions:

    1. Go to your organisation | Settings | Member privileges.
    2. Under 'Repository deletion and transfer', ensure 'Allow members to delete or transfer repositories for this organization' is deselected
    3. Save

    See GitHub docs Setting permissions for deleting or transferring repositories

    This will ensure that even Admin users cannot accidentally delete or transfer repositories

    dontAllowDeletion
    Figure: 'Allow members to delete or transfer repositories for this organization' is disabled

  16. Do you use branch protection?

    Disabling the 'Allow force pushes' and 'Allow Deletions' settings on your main branch will protect the branch from being accidentally deleted and the history from being rewritten.

    Using force push is dangerous and should be used with extreme caution, as it will override other contributor's changes with your own — and it won't stop to check if it will override any changes pushed up to remote in the process.

    1. Go to your repo | Settings | Branches
    2. If it doesn't already exist, create a branch protection rule on the 'main' or 'master' branch
    3. Ensure 'Allow force pushes' and 'Allow Deletions' are disabled
    4. Save changes

    branchProtection
    Good Example: Main branch is protected

    See the GitHub docs Managing a branch protection rule

    If you need to check that your code changes will build, you can use required status checks. Status checks are GitHub Actions that are required to succeed before the PR can be merged, so developers wont be able to merge failing code. You can enable required status checks in the same location as 'Allow force pushes' and 'Allow Deletions'.

    requiredChecks
    Figure: Developers can't merge until all checks have passed

    See the GitHub docs Require status checks before merging

  17. Do you use teams?

    You can use teams within a repository to manage a whole group's permissions instead of setting permissions for each new member of the organisation.

    See Organizing members into teams.

    GoodExampleUsingTeams
    Figure: Using a good teams structure to organise access

    Correctly configuring your organisation's teams structure will make it easy to give members the permissions level that they need. You can add teams to repositories to manage their roles.

    TeamsOnRepo
    Figure: Good Example - Using teams to assign roles in a repository

    Another benifit of using teams is that you can metion a whole team in a discussion instead of individual members. See Mentioning people and teams

    See docs for here.

  18. Increasing a member's permissions also increases the amount of damage they can do. As a good rule of thumb, only give members the access that they need to complete their work.e.g. You do not want developers to have force-push permissions on the main branch, as they might accidentally delete branches and code by mistake!Note: If you are still using Azure DevOps, force-push permissions into a repo is only allowed for Project Administrators, so pick your administrators well.

    See GitHub docs Repository permission levels for an organization

    tooManyAdmins
    Bad Example: All members are Admins

    notManyAdmins
    Good Example: Only one admin

  19. Using GitHub Webhooks, you can set some default permissions for every new repository inside an organisation.

    You can use the repository event to trigger a GitHub action to set the permissions.

    See the GitHub docs Permissions API

    Add example of a GitHub action that sets the permissions

    By adding this to your organisation,every new repo will already have the optimal permissions and privileges.

  20. GitHub notifications can be frustrating if they are not setup for your personal preferences. For example, you may not want to receive an email everytime an automated GitHub action runs against the repo. To configure how many and how you receive your GitHub notifications follow this process.

    1. From GitHub Profile Dropdown | Settings | Notifications
      Figure: First navigate to your notifications
    2. Customise the settings as you see fit.
      Figure: The recommended notification setup for non-technical users

    From the default remove:

    • Automatic watching x2
    • Dependabot alerts x5
    • GitHub Actions x1
    • Email notification preferences | Pull Request pushes x1
  21. GitHub Issues - Do you use Issue Templates?

    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...

    bad example issue
    Figure: Bad Example - Issue created without a Template

    good example issue
    Figure: Good Example - Issue created from a Template

    list of options
    Figure: Good Example - All the available Issue Template

    For instructions on setting this up:

  22. Do you configure your GitHub Notifications?

    Notifications from GitHub can be quite a pain, as they send a lot of emails. This leads to many developers ignoring the important emails they receive.

    notifications
    Figure: Bad example - lots of notifications

    To reduce this spam and to make the notifications have value, make sure to configure your GitHub Notifications.

    screen shot 2022 03 03 at 2 20 33 pm
    Figure: Good example - disable workflow notifications

    The important one here is to make sure the item marked Send notifications for failed workflows only is checked, so that you receive emails for failures in your deployments.

We open source. Powered by GitHub