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?

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

    ​​github-pullrequest-1.png
    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.png
    Figure: See how easy it is to see the code rejected​



    Useful resources - learn about Pull Requests


    https://www.visualstudio.com/learn/git-pull-requests/
    https://www.visualstudio.com/en-us/docs/git/pull-requests/
    https://yangsu.github.io/pull-request-tutorial/​
     ​
  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.​
    issues_bad_example.png
    ​​​Bad Example: It is hard to understand what issues are being worked on

    ​​

    issues_good_example.png
    ​​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.

    view-project-1.png
    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.png
    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.png
    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.png
    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​

  6. 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.png
    ​Bad example - Pull request with vague title and no description
    better-pr-good-pr.png
    ​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.

    3. ​​Link the pull request to the associated issues / PBIs

    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.png
    ​Figure: Linking a pull request to the related issue
    better-pr-link-issues-linked.png
    ​Figure: A pull request is now associated with the related ​issue

  7. 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 http://choosealicense.com/no-license/
    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. 
  8. 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: https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-users-and-teams

    ​​github-mention-bad.png
    Figure: Bad example - Not using a @mention when addressing Duncan or Igor​
    github-mention-good.png
    Figure: Good example - Using a @mention
  9. 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.​
  10. Do you know where to discuss the backlog?

    When discussing a​ PBI/Issue, Pull Request, or a project in general, it is important to do it in the right place.

    Scrum1.jpg
    bad-mention-pbi.jpg
    Figure: Bad Example – don't use emails to discuss tasks

    For code

    Sometimes developers need to discuss code implementations - sometimes to improve the code, other times to explain why something was done a certain way.

    This should be done in the Pull Request, if possible comment directly on the line of the code change and once resolved, make sure that the important information is captured in the merge's commit description.

    Figure: You can add a comment on a specific line of code

    For a new PBI/Issue

    As per Do you know when you use @ mentions in a PBI?​ - ​Create a new issue mentioning the Product Owner and the related people

    Create-Issue.png
    Figure: Good Example - ​When adding a GitHub issue, @ mention the Product Owner and other related people so they receive a notification e.g, an email

    For an existing PBI/Issue

    Discuss it in the existing PBI/Issue.

    existing issue discussion.png
    Figure: You can discuss an existing issue, even when it has been closed

    For other topics (brainstorm ideas, general discussion, etc.​)

    You can:

    • Create a PBI/Issue
      • use a "discussion" label so that others know that it is just a discussion point and not actionable work yet​
      • have it checked by the client before publishing it (recommended)
    • Discuss it in the discussion tab in GitHub​
    Discussion Tab in GitHub.png
    Figure: You can create discussions on your project using the Discussion tab in your GitHub repository
    • In the team channel in Teams
    Team channel.png
    Figure: You can discuss your idea in Teams on the team channel​

    In summary, Email should be the last resort.​

  11. Do you write nice commit messages?

    ​​​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.png
    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.jpg
    Good Example: Great use of emoji and concise message
    emojis-list.jpg
    Figure: see what emojis work best with each topic here: gitmoji.carloscuesta.me/
  12. Product Owner - Do you know how to update the backlog?

    All good Scrum teams have a backlog. The backlog is built by taking a conversation and recording it as one or more Product Backlog Items (PBIs) (e.g. Azure DevOps) or Issues (e.g. GitHub)

    We recommend using software such as GitHub Issues, Azure DevOps, or JIRA to store PBIs straight after or, better yet, during the conversation, rather than using emails that may never be entered into the backlog.

    Typing.jpg
    Figure: Get typing during a conversation to make the meeting tangible

    The Product Owner is responsible for owning the Product Backlog. See the video on "Do you know how to be a good Product Owner?"

    1. Emails​​​​​​​
      EmailBadExample.png
      Bad Example - This is a poor way to add a PBI/Issue​ as you can’t order emails by the business priority​
    2. GitHub Issues (Recommended)
      GitHubIssues.png
      Figure: Good Example - Github Issues
    3. Azure DevOps - E.g. https://ssw.visualstudio.com
      AzureDevOpsBacklog.png
      ​​​​Figure: Good Example - Azure DevOps allows you to enter an item into the backlog, in any priority order​​​​