​

​​

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

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

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]

​

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

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

​

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.

Figure: Searching for repositories by topic

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

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

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

​

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

​

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

​

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

​

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

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"

​​​Pull request title: "Fix desktop app exporting - prevent database concurrent access while exporting"

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

​

​Bad example - Pull request with vague title and no description

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

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.

​Figure: Linking a pull request to the related issue

​Figure: A pull request is now associated with the related ​issue

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. 

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

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

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.

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​
  

Figure: You can create discussions on your project using the Discussion tab in your GitHub repository

• In the team channel in Teams

Figure: You can discuss your idea in Teams on the team channel​

In summary, Email should be the last resort.​

Here's a quick guide in setting it up for your GitHub Repository and Azure DevOps.​

1. Install the Azure Boards App from the GitHub Marketplace
2. Create the GitHub Action secrets​

• ​​ADO_PERSONAL_ACCESS_TOKEN (Azure DevOps | User settings | Security | Personal access tokens)
  The Azure Personal Access Token requires "read & write" permission for Work Items.
  
• GH_PERSONAL_ACCESS_TOKEN (GitHub | Personal settings | Developer settings | Personal access tokens)
  The GitHub Personal Access Token​ requires "repo" permissions.
  
• ADO_ORGANIZATION (https://ssw.visualstudio.com/SSW.Rules)
  The Organization name is in your Azure DevOps URL.
  
• ADO_PROJECT (https://ssw.visualstudio.com/SSW.Rules)​
  ​The Project name can also be found in your Azure DevOps URL.
  

3. Create the following GitHub Action​

e.g.​ SSW uses this template for their projects, you may need to change the new and closed states depending on your environment.

​​​name: Sync issue to Azure DevOps work item
on:
  issues:
    types:
      [opened, edited, deleted, closed, reopened, labeled, unlabeled, assigned]

jobs:
  alert:
    runs-on: ubuntu-latest
    steps:
      - uses: danhellem/github-actions-issue-to-work-item@master
        env:
          ado_token: "${{ secrets.ADO_PERSONAL_ACCESS_TOKEN }}"
          github_token: "${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}"
          ado_organization: "${{ secrets.ADO_ORGANIZATION }}"
          ado_project: "${{ secrets.ADO_PROJECT }}"
          ado_wit: "Product Backlog Item"
          ado_new_state: "New"
          ado_close_state: "Done"
          ado_bypassrules: true

​Figure: Good Example - GitHub Issues Syncing to Azure DevOps
​

​Pros​

• ​Easily manage sprints and calculate burndown and cycle time
  
• See all your GitHub Issues and Azure DevOps PBIs in one backlog
  
• Automated tagging and hyperlinking between Issues and PBIs​
  

Cons

• The sync is only one-way GitHub Issues -> Azure DevOps Backlog
  
• ​It won’t sync existing GitHub Issues unless they are updated
  

1. Emails​​​​​​​

   
   

   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)

   ​ ​
   

   Figure: Good Example - Github Issues
   

3. Azure DevOps - E.g. https://ssw.visualstudio.com

   

   ​​​​Figure: Good Example - Azure DevOps allows you to enter an item into the backlog, in any priority order​​​​

• What's next? Discuss the backlog
• What to do when it's done?