diff --git a/_config.yml b/_config.yml index 2b6226a81..434f152ab 100644 --- a/_config.yml +++ b/_config.yml @@ -93,6 +93,7 @@ extras_order: - guide - common-issues - discuss + - protect-main-branch - vscode - functional-programming - persistence diff --git a/_episodes/41-code-review.md b/_episodes/41-code-review.md index 15b8c7fd5..f9414206e 100644 --- a/_episodes/41-code-review.md +++ b/_episodes/41-code-review.md @@ -30,29 +30,35 @@ and improve our code by engaging in code review process with other team members. > the type of development model you use in your project. > Two commonly used models are: > -> - **fork and pull model** - -> where anyone can **fork** an existing repository -> (to create their copy of the project linked to the source) -> and push changes to their personal fork. -> A contributor can work independently on their own fork as they do not need -> permissions on the source repository to push modifications to a fork they own. -> The changes from contributors can then be **pulled** into the source repository -> by the project maintainer on request and after a code review process. -> This model is popular with open source projects as it -> reduces the start up costs for new contributors -> and allows them to work independently without upfront coordination -> with source project maintainers. -> So, for example, you may use this model when you are an external collaborator on a project -> rather than a core team member. -> - **shared repository model** - -> where collaborators are granted push access to a single shared code repository. -> Even though collaborators have write access to the main development and production branches, -> the best practice of creating feature branches for new developments -> and when changes need to be made is still followed. -> This is to enable easier testing of the new code -> and initiate code review and general discussion about a set of changes -> before they are merged into the development branch. -> This model is more prevalent with teams and organisations collaborating on private projects. +> * Fork and pull model +> * Shared repository model +> +> **Fork and Pull Model** +> +> In this model, anyone can **fork** an existing repository +> (to create their copy of the project linked to the source) +> and push changes to their personal fork. +> A contributor can work independently on their own fork as they do not need +> permissions on the source repository to push modifications to a fork they own. +> The changes from contributors can then be **pulled** into the source repository +> by the project maintainer on request and after a code review process. +> This model is popular with open source projects as it +> reduces the start up costs for new contributors +> and allows them to work independently without upfront coordination +> with source project maintainers. +> So, for example, you may use this model when you are an external collaborator on a project +> rather than a core team member. +> +> **Shared Repository Model** +> +> In this model, collaborators are granted push access to a single shared code repository. +> By default, collaborators have write access to the main branch. +> However, it is best practice to create feature branches for new developments, +> and protect the main branch. See the extra on [protecting the main branch](../protect-main-branch) +> for how to do this. +> While it requires more upfront coordination, it is easier to share each others +> work, so it works well for more stable teams. +> This model is more prevalent with teams and organizations collaborating on private projects. {: .callout} Regardless of the collaborative code development model you and your collaborators use - diff --git a/_extras/protect-main-branch.md b/_extras/protect-main-branch.md new file mode 100644 index 000000000..b358f726e --- /dev/null +++ b/_extras/protect-main-branch.md @@ -0,0 +1,41 @@ +--- +title: "Additional Material: Protecting the Main Branch on a Shared GitHub Repository" +--- + +## Introduction + +By default, any collaborator can push to any branch on a shared repository. +It is possible to prevent this by "protecting" the main branch. + +This has a number of advantages: + +* Avoids someone accidentally pushing work-in-progress changes to the branch + that everyone else downloads. +* Ensures everyone follows a code review process. +* Ensures all changes are checked by continuous integration. + +## How to protect the main branch + +To protect the main branch in GitHub, go to the repository settings, select `Branches`. +Click `Add Rule`. Type in the name of your main branch (e.g. `main` and/or `develop`). +Tick the check box saying require pull requests. This will ensure all changes to the +branch are done via a pull request. + +![GitHub add a branch protection rule settings screen with recommended settings enabled for a branch called main](../fig/github-branch-protection-settings.png) + +It is recommended to also tick `Require approvals`. + +This means someone besides the person who raised the pull request will need to approve the change. + +It is also recommended to tick `Require status checks before merging`. + +This ensures that CI has run successfully before allowing the changes to be made. + +Finally, it is recommended to tick `Do not allow bypassing the above settings`. + +This means that administrators of the repository will have to follow the same process to. +If there becomes a need to push to the main branch, these settings can be changed +by administrators to allow this, setting this means that administrators cannot push by mistake +during the normal course of their work. + +See [GitHubs documentation for more information about protecting branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule). diff --git a/fig/github-branch-protection-settings.png b/fig/github-branch-protection-settings.png new file mode 100644 index 000000000..7e3434a7f Binary files /dev/null and b/fig/github-branch-protection-settings.png differ