Merge pull request #230 from thomaskileyukaea/move-branch-protection-to-extras

Move branch protection to extras

Author: anenadic

_config.yml

@@ -93,6 +93,7 @@ extras_order:
   - guide
   - common-issues
   - discuss
+  - protect-main-branch
   - vscode
   - functional-programming
   - persistence

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

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