Rules to Better GitHub

Hold on a second! How would you like to view this content?
Just the title! A brief blurb! Gimme everything!
Rules to Better GitHub
  1. Do you enable pull requests to ensure code is reviewed?

    Figure: Bad example - Every developer commits to the master branch, code is not reviewed, and code quality is poor
    Figure: Bad example - Use the out of the box pull requests to ensure all code is reviewed

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

    Figure: Bad example – Repository names are not consistently formatted
    Figure: OK example – Repositories are following the lower-cased hyphenated format that is common for open source projects
    Figure: ​​​Good example – Repository names are name-spaced in the format [CompanyName].[ProjectName]
  3. Do you know how to structure a project for GitHub?

    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.

    Figure: Bad Example – T​he folder containing the source code is called ‘trunk’ rather than ‘src’. There is no docs folder containing the important documents as per Do you review the documentation?
    Figure: Good example - All documentation Is in the ‘docs’ folder, samples are in the ‘samples’ folder and all the source code is in the ‘src’ folder
  4. Do you know how to use labels for GitHub Issues?

    ​It is important that you know how to use labels for GitHub issues when using an open source project on GitHub.

    Managing your labels on GitHub issues will let the community feel professional and make it easier to work with as it is predictable
    When you are using an internal project management solution (such as Azure DevOps) for an open source project. It is a good idea to use labels to demonstrate that an issue is being worked on to 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

  5. Do you know how to view a project’s activity, traffic and contributions?

    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.

    Figure: Under your project name, click Insights

    Read more about the project’s graphs:

    Some project graphs available:

    ​Pulse Graph

    Figure: Pulse graph shows a summary of the project activity

    Read more about Pulse Graph:​

    ​​Contributors Graph

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

    Read more about Contributors Graph:​

    ​Traffic Graph

    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:​

  6. Do you know the correct license to use for Open Source software?

    More and more projects are being created as Open Source. However just because you’re created an open source project doesn’t mean you give everything in your cookie jar away. You should only release your code subject to a licence agreement. A common confusion when putting projects onto Open Source platforms like GitHub is ‘What License Should I Use?”. We have our own opinions but we aren’t lawyers so if you want to know what’s best for you speak with your lawyer.

    Figure: Bad Example - No License -​ Generally speaking, the absence of a license means that default copyright laws apply. This means that you retain all rights to your source code and that nobody else may reproduce, distribute, or create derivative works from your work. For more information read
    Figure: Good Example - GPL License – For projects where you want consumers of your code to share their changes. Anyone who distributes your code or a derivative of your code must make the source available under the same terms. Warning: Consider carefully before using on components to be used in commercial applications due to the CopyLeft requirement. Used by Linux, Git, WordPress -​ GNU General Public License on Wikipedia
    Figure: Good Example - MIT License - for projects where you are happy for people to do anything with your code. Use for .Net core, jQuery and Node.js - MIT License on Wikipedia
    Figure: Good Example – Apache License - for projects where you require attribution. Microsoft use the Apache license for MVC, EntityFramework, SignalR and Roslyn - Apache License on Wikipedia - Used for all SSW Open Source Projects. 
  7. Do you know to mention someone with a @mention when you make a pull request or comment on GitHub?

    ​When you make a pull request or need to communicate the next actions someone needs to take in a GitHub comment, you should use a @mention.

    Read more about @mention:

    Figure: Bad example - Not using a @mention when addressing Duncan or Igor​
    Figure: Good example - Using a @mention
  8. Do you know to the requirements to create a new repository?

    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.
    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
    Figure: Good Example – As well as a good repository name and description, a ReadMe, .gitignore and license will be included in the repository.​