Rules

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.

Useful resources - learn about Pull Requests

• https://docs.microsoft.com/en-us/azure/devops/repos/git/pull-requests?view=azure-devops
• https://yangsu.github.io/pull-request-tutorial/

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.

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

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.

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

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.

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

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

Contributors Graph

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

Traffic Graph

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

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"

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.

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.

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.

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.

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

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.

For a new PBI/Issue

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

For an existing PBI/Issue

Discuss it in the existing PBI/Issue.

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

• In the team channel in Teams

In summary, Email should be the last resort.

If you store all your code in GitHub, why not create all your issues there too?

You might be reluctant to move your backlog to GitHub from Azure DevOps as you don’t want to lose the metrics functionality.

But you can easily sync all your GitHub Issues to Azure DevOps automatically to have the best of both worlds.

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

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

More information about this GitHub Action can be found here https://github.com/danhellem/github-actions-issue-to-work-item

To avoid people adding a PBI to the Azure DevOps, add a PBI at the top of your backlog to indicate that they should add it to GitHub issues.

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

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

h 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)

Good Example: Great use of emoji and concise message


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.

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

::: bad

:::

2. GitHub Issues (Recommended)

::: good

:::

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

::: good

:::

What's next?

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

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

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

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

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

See the GitHub docs Managing a branch protection rule

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.

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.

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.

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.

See GitHub docs Repository permission levels for an organization

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

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

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

   

2. Customise the settings as you see fit.

   

From the default remove:

• Automatic watching x2
• Dependabot alerts x5
• GitHub Actions x1
• Email notification preferences | Pull Request pushes x1