Update github-configuration.md

... still working on this....

Mostly these changes replace the word "enterprise" for "organization" when talking about configuration at the enterprise level.

Author: JustinGOSSES

tooling/github-configuration.md

@@ -1,5 +1,6 @@
 # GitHub InnerSource Configuration
 
+- [Layering Source Control Management Configurations](#layering-source-control-management-configurations)
 - [Enterprise Setting](#enterprise-setting)
   - [Repository policies](#repository-policies)
     - [Base permissions](#base-permissions)
@@ -14,47 +15,37 @@
   - [GitHub Connect - Server statistics](#github-connect---server-statistics)
 - [Resources](#resources)
 
-## Enterprise Setting
 
-#### Layering Source Control Management Configurations
+## Layering Source Control Management Configurations
 In GitHub, configuration can be set at different levels. In general, configuration set at the enterprise level will overrule or constrain organizational configuration which will do the same for repository level configuration.
-Sometimes a configuration settings disables options at lower levels. Other times a configuration setting at the enterprise or organization level only sets the default option that is prechecked. It can be changed by a user who takes an additional action at the repository level. Due the overlapping nature of the policies, it is important to pick the right layer to apply a configuration.
-In general, use caution when picking configuration settings at the enterprise or organization level that restrict reasonable choies at the repository level. Nudging with defaults can be better than disabling options enterirely.
+Sometimes a configuration settings disables options at lower levels. Other times a configuration setting at the enterprise or organization level only sets the default option that is prechecked. A user who takes an additional actions can pick a different configuration at the repository level if only the default option is set. Due the overlapping nature of the policies, it is important to pick the right layer to apply a configuration: enterprise, organization, or repository.
+In general, use caution when picking configuration settings at the enterprise or organization level that restrict reasonable choies at the repository level. These can add friction to the developer experience and even promot shadow IT in the worse cases. Nudging with defaults can be better in some circumstances than disabling options enterirely.
 If you have repositories that must be extremely tightly controlled, consider mandating that type of repository go into special organizations set up for those constraints instead of trying to apply those constrains on all enterprise code.
 
-### Repository policies set an Organization Level
+## Enterprise Setting
+
+### Repository policies set at Enterprise Level
+If your GitHub organization is part of an enterprise on GitHub, there are enterprise level configuration settings that administrators of that Enterprise can change. If you are not an enterprise admin, you will likely not even be able to see these settings.
 
 #### Base permissions
 
-[Base permissions](https://docs.github.com/en/organizations/managing-organization-settings/managing-base-permissions-for-projects) are permissions that are applied to all of an organization’s repositories from the organization level. They are given to all members of the organization, excluding outside collaborators. Since organization members can have permissions from multiple sources, members and collaborators who have been granted a higher level of access than the base permissions will retain their higher permission privileges. When setting up the base repository permissions to promote InnerSource within your organization on GitHub, it's important to strike a balance between transparency, collaboration, and respecting constraints and limitations. Here are some best practices for setting up repository permissions:
+[Base permissions](https://docs.github.com/en/organizations/managing-organization-settings/managing-base-permissions-for-projects) are permissions that are applied to all of an organization’s repositories from the organization level. They are given to all members of the organization, excluding outside collaborators. Since enterprise members can have permissions from multiple sources, members and collaborators who have been granted a higher level of access than the base permissions will retain their higher permission privileges. For example, if someone was granted write access at the repository level, but their enteprise base permissions only give them read access, they will still return write access. When setting up the base repository permissions to promote InnerSource within your enterprise on GitHub, it's important to strike a balance between transparency, collaboration, and respecting constraints and limitations. 
 
 | Repository Permission | Description |
 | --- | --- |
-| No Permission |  Selecting this means organization membership gives users no permissions to read, write, or admin any repositories in the organization. If not compared with other methods of extending permissions, especially read permissions, this will result in making the organization's repositories hard to discovery, find, or collaborate. |
+| No Policy | Repository read, write, admin permissions are defined at organization or repository level entirely. This option provides for the most flexibility for projects with unique permission needs. |
+| No Permission |  Selecting this means enterprise membership gives users no built-in permissions to read, write, or admin any repositories in the organization. 
 | Read | All organization members can view the repository's contents, promoting transparency and allowing employees to learn from each other's work. |
 | Write | All organization members will have the "Write" permission. They will able to make commit contributions to the repositories and approve pull requests. |
 | Admin | All organization members will have "Admin" permissions to all repositories in the organization, including clone, pull, and add new collaborators. |
 
-"No Permission" or "READ" are common options to choose. Selecting "Read" gives every member of the organization read permissions to EVERY repositories in the organization, even if the repositories visibility is set to private. Many times this is fine and the preferrable option. 
-
-##### Enabling wide and narrow sharing from a single organization.
-If you want to enable both wide and narrow sharing within a single organization, then the base permissions setting of "No Permission" combined with two other configurations might be preferrable. 
-
-In situations where it is important to have a single organization be able to hold:
-- Repositories shared to anyone in the enterprise
-- Repositories shared to anyone in the organization
-- Repositories shared to a more limited subset of users
-  
-... Then 3 settings should be combined:
-1. "No Permissions" should be selected for the base repository permissions for an organization.
-2.  Ensure repositories can opt into sharing with everyone in the enterprise by giving repository owners the permission to pick "internal visibility" upon creation at a later date. This is normally available by default, but it can be disabled at the organization or enterprise level. Optionally, there is an organizational policy to set "internal visibility" as the default visibility. Default means repository owners can select to have the repository be private but internal is the pre-checked selection.
-3. To ensure it is low friction for all organization members to have READ access for most repositories in the organization, set up a GitHub team that mirrors that organization's membership. Repository owners that want to share READ permissions to their repository with any member of the organization, can add that team to their repository. 
+*To avoid confusion, please note that "No Policy" is an option at the enterprise level, but it is not an option at the organization level.*
 
+"No Policy" or "READ" are common choices. 
+Selecting "Read" gives every member of the enterprise read permissions to EVERY repository. There are circumstances where this is acceptable based on who the gets membership to the enterprise and what type of code is being stored there. In many other cases, "No Policy" is the best option as it allows for the most flexibility. In large enterprises with many organiations, different organizations will want different base repository permissions, "No Policy" enables each organization to pick their own configuration.
 
 #### Repository creation
-
-Allowing most users to create only Private or Internal type repositories is a measure often taken.
-It's important to consider your organization's policies and the nature of the projects when deciding on repository creation settings. Striking a balance between encouraging collaboration and managing access to sensitive information is crucial in an InnerSource context. Providing options for members to create repositories, while defining guidelines and permissions, can support innovation and knowledge sharing within the organization.
+Enterprise configuration on repository creation restricts who can create a new repository and with what visibility across the entire enterprise. There is also an organization-level configuration setting that controls repository creation within each organization.
 
 | Repository Creation | Description | Recommendation |
 | --- | --- | --- |
@@ -65,21 +56,23 @@ It's important to consider your organization's policies and the nature of the pr
 | ┣  Private | Members can create private repositories accessible only to invited collaborators. | Encourage team-specific or sensitive projects that require restricted access. |
 | ┗ Internal | Members can create internal repositories visible to organization members. | Foster collaboration and knowledge sharing within the organization while keeping information proprietary. |
 
+##### Minimizing accidental public disclosure and enabling quick InnerSource via forking
 Restricting who can make a repository public or adding process around that workflow is an important control to minimize the risk of code being made public that should not be made public. 
-
-It is worth noting here that some companies may have entirely separate Github instances for different combinations of public facing code, private code collaboration with external partners, internal code collaboration across the entire company, or code collaboration within a subset of the company. In the situation where a company has one GitHub instance for internal code and one or more organizations on the public-facing github.com for open-source, they might turn off the ability to create any repositories under public visibility in the GitHub Enterprise instance specifically for internal code. This has the additional benefit of making it less risky to let repository owners change their repository visibility themselves and less risky to enable repository forking.
+Allowing most users to create only Private or Internal visibility repositories is a measure sometimes taken for this reason. Sometimes creation of public facing repositories is limited to a group of admins. Other times public-facing code and internal code development is done on entirely separate GitHub Instances. In the situation where a company has one GitHub instance for internal code and one or more organizations on the public-facing github.com for open-source, they might turn off the ability to create any repositories under public visibility in the GitHub Enterprise instance specifically for internal code. This has the additional benefit of making it less risky to let repository owners change their repository visibility themselves and less risky to enable repository forking.
 
 **Having different GitHub instances for public-facing and internal code can reduce risk of accidental disclosures.**
 
 Some companies also have add-on systems that handle repository creation. This can be useful if an enterprise wnats to capture additional information from repository creators at time of repository creation, programmatically inject standard files or create metadata in other IT systems at the same time. 
 
+It's important to consider your organization's policies and the nature of the projects when deciding on repository creation settings. Striking a balance between encouraging collaboration and managing access to sensitive information is crucial in an InnerSource context. Providing options for members to create repositories, while defining guidelines and permissions, can support innovation and knowledge sharing within the organization.
+
 #### Repository forking (Private / Internal)
 
 The decision to allow or restrict repository forking depends on your organization's policies and the level of control and security required for your codebase. Enabling forking generally promotes collaboration, allows for experimentation, and encourages the InnerSource principles of sharing and contribution. However, it's important to assess the risks and consider any regulatory or compliance requirements before allowing forking in private and internal repositories.
 
 | Repository Forking | Description | Recommendation |
 | --- | --- | --- |
-| No Policy | Organizations choose whether to allow private and internal repositories to be forked. | Provide flexibility for forking private and internal repositories based on project needs. This allows teams to collaborate and contribute to codebases while maintaining control over access and security. |
+| No Policy | If no policy set at Enteprise-level, then organizations choose whether to allow private and internal repositories to be forked. | Provide flexibility for forking private and internal repositories based on project needs. This allows teams to collaborate and contribute to codebases while maintaining control over access and security. |
 | Enabled | Organizations always allow private and internal repositories to be forked. | Encourage forking of private and internal repositories to promote collaboration and foster a culture of contribution. Forking enables individuals or teams to make modifications and propose changes without directly impacting the original codebase. |
 | Disabled | Organizations never allow private or internal repositories to be forked. | In an InnerSource context, it is recommended to enable forking to encourage collaboration, knowledge sharing, and innovation. Forking allows individuals or teams to experiment, improve, and contribute without directly modifying the original codebase. |
 
@@ -88,6 +81,14 @@ The decision to allow or restrict repository forking depends on your organizatio
 ### Member privileges
 
 #### Base permissions
+The difference between base permissions at organization level vs. enterprise level described above on this page is there is no longer a "No Policy" option. 
+
+| Repository Permission | Description |
+| --- | --- |
+| No Permission |  Selecting this means organization membership gives users no permissions to read, write, or admin any repositories in the organization. If not compared with other methods of extending permissions, especially read permissions, this will result in making the organization's repositories hard to discovery, find, or collaborate. |
+| Read | All organization members can view the repository's contents, promoting transparency and allowing employees to learn from each other's work. |
+| Write | All organization members will have the "Write" permission. They will able to make commit contributions to the repositories and approve pull requests. |
+| Admin | All organization members will have "Admin" permissions to all repositories in the organization, including clone, pull, and add new collaborators. |
 
 At the Organization Level, you can further refine repository permissions within specific organizations. This allows you to tailor access control to each organization's unique requirements. Some recommended practices for repository permission settings at the Organization Level include:
 
@@ -96,6 +97,18 @@ At the Organization Level, you can further refine repository permissions within
 - Granting write access to individuals or teams actively participating in InnerSource projects, who have demonstrated the necessary skills and knowledge.
 - Designating a select group with admin permissions responsible for managing repositories, overseeing InnerSource initiatives, and maintaining repository settings.
 
+##### Enabling wide and narrow sharing from a single organization using base permissions in combination with other configuration
+If you want to enable both wide and narrow sharing within a single organization, then the base permissions setting of "No Permission" combined with two other configurations might be preferrable. 
+In situations where it is important to have a single organization be able to hold all of the following:
+- Repositories shared to anyone in the enterprise
+- Repositories shared to anyone in the organization but not anyone in the enterprise
+- Repositories shared only to a more limited subset of users
+  
+... Then 3 settings should be combined:
+1. "No Permissions" should be selected for the base repository permissions for an organization.
+2.  Ensure repositories can opt into sharing with everyone in the enterprise by giving repository owners the permission to pick "internal visibility" upon creation at a later date. This is normally available by default, but it can be disabled at the organization or enterprise level. Optionally, there is an organizational policy to set "internal visibility" as the default visibility. Default means repository owners can select to have the repository be private but internal is the pre-checked selection.
+3. To ensure it is low friction for all organization members to have READ access for most repositories in the organization, set up a GitHub team that mirrors that organization's membership. Repository owners that want to share READ permissions to their repository with any member of the organization, can add that team to their repository. 
+
 #### Repository creation
 
 When configuring repository creation settings at the Organization Level, it's essential to align them with your organization's goals, policies, and security requirements. Allowing members to create repositories with specific types (public, private, internal) provides flexibility and promotes InnerSource practices.
@@ -112,6 +125,10 @@ When making a decision about forking from private and internal repositories for
 | Project Scope and Collaboration Scope | Determine the scope of the InnerSource project and the desired collaboration boundaries. If the project involves cross-functional teams or collaboration with external contributors, allowing forking from private and internal repositories may promote broader engagement and involvement. |
 | Internal Policies and Compliance | Consider any internal policies, regulations, or compliance requirements that may impact the decision to allow forking from private and internal repositories. Ensure that the practice aligns with your organization's guidelines and legal obligations. |
 
+## Repository-level Settings
+
+__________________ TO DO _______________
+
 ## GitHub Enterprise Server Setting
 
 ### GitHub Connect - Server statistics