A nested GitHub team cannot be secret (#298)

Author: stefaniuk

practices/security-repository.md renamed to practices/securing-repositories.md

@@ -1,6 +1,6 @@
-# Securing repositories
+# Securing Repositories
 
-- [Securing repositories](#securing-repositories)
+- [Securing Repositories](#securing-repositories)
   - [Prerequisites](#prerequisites)
   - [Access controls](#access-controls)
     - [Organisation-level settings](#organisation-level-settings)
@@ -35,14 +35,16 @@ This guide lays out security best practice for Github repositories. This set of
 
 ### Teams setup
 
-Because of baseline visibility configurations, you must setup Github teams in order to provide team members access to repos. The minimum recommended setup is as follows:
+Because of baseline visibility configurations, you must setup GitHub teams in order to provide team members access to repositories. The minimum recommended setup is as follows:
 
 - Create one team with the name of your programme (e.g. `Engineering Quality Framework`). Add all required members to this team.
-- Create one child team within the team, for admins only (e.g. `Engineering Quality Framework Admins`). Add admins only to this team. Set the visibility of the team to `Secret`.
-- Create a second child team, for code owners (e.g. `Engineering Quality Framework Code Owners`). Add relevant members to this team, and reference in the CODEOWNERS file (example [here](https://github.com/NHSDigital/software-engineering-quality-framework/blob/master/.github/CODEOWNERS)). Set the visibility of the team to `Secret`.
+- Create one child team within the team, for admins only (e.g. `Engineering Quality Framework Admins`). Add admins only to this team.
+- Create a second child team, for code owners (e.g. `Engineering Quality Framework Code Owners`). Add relevant members to this team, and reference in the CODEOWNERS file (example [here](https://github.com/NHSDigital/software-engineering-quality-framework/blob/master/.github/CODEOWNERS)).
 - For each repo in your programme (e.g. `software-engineering-quality-framework`), under the `Manage Access` option in `Settings`, set the general team to have `Write` access and the admins team to have `Admin` access.
 
-Depending on your use case, you may want to create additional teams (e.g. a read-only access team, or different teams granting access to different projects). This is welcomed by the framework, as long as the teams provide clarity on the role they encompass, remain consistent and are applied consistently to your repos.
+Child teams inherit the parent's access permissions, simplifying permissions management for large groups. Members of child teams also receive notifications when the parent team is `@mentioned`, simplifying communication with multiple groups of people.
+
+Depending on your use case, you may want to create additional teams (e.g. a read-only access team, or different teams granting access to different projects). This is welcomed by the framework, as long as the teams provide clarity on the role they encompass, remain consistent and are applied consistently to your repositories.
 
 ## Code security
 

tech-debt.md

@@ -41,7 +41,7 @@ Here is a non-exhaustive list of examples we consider to be *in* scope of "techn
 * Code you no longer need ([e.g. a new managed service is available](patterns/outsource-bottom-up.md))
 * Technologies no longer needed (e.g. you've introduced something better than what you used before)
 * CI issues, e.g. lack of [fast feedback](patterns/fast-feedback.md), or intermittent [build failures](practices/continuous-integration.md)
-* [Code-repository configuration issues](practices/security-repository.md), e.g. lack of branch protection rules
+* [Code-repository configuration issues](practices/securing-repositories.md), e.g. lack of branch protection rules
 * Manual processes that could be [automated](patterns/automate-everything.md)
 * Software components with inappropriate / confused [domain boundaries](patterns/architect-for-flow.md)
 * Use of obsolete / unsupported technologies