DOC Update contributing code docs

- Move note about docs to "before working on a fix" since everything until then is relevant for docs too
- Remove note that "Every file view on GitHub has an 'edit this file" link.' because that's confusing at best
- Move definition of public API to its own page and refer to it always as "public API", not just "API"
- fix a link

en/02_Developer_Guides/05_Extending/00_Modules.md

@@ -182,7 +182,7 @@ which the Silverstripe CMS project applies to the modules it creates and maintai
  * The module is a Composer package.
  * All Composer dependencies are bound to a single major release (e.g. `^4.0` not `>=4` or `*`).
  * There is a level of test coverage.
- * A clear public API documented in the docblock tags.
+ * A clear [public API](/project_governance/public_api/) documented in the docblock tags.
  * Code follows [PSR-1](http://www.php-fig.org/psr/psr-1/) and [PSR-2](http://www.php-fig.org/psr/psr-2/) style guidelines.
  * `.gitattributes` will be used to exclude non-essential files from the distribution. At a minimum tests, docs, and IDE/dev-tool config should be excluded.
  * Add a [PSR-4 compatible autoload reference](https://getcomposer.org/doc/04-schema.md#psr-4) for your module.

en/05_Contributing/01_Code.md

@@ -6,10 +6,6 @@ icon: code
 
 # Contributing Code - Submitting Bugfixes and Enhancements
 
-[info]
-If you want to contribute changes to documentation, please read through the [contributing documentation](./documentation) page.
-[/info]
-
 The Silverstripe CMS core and supported modules are hosted on [GitHub](https://github.com) - mostly in [github.com/silverstripe](https://github.com/silverstripe/). To contribute code, you will need to [create a GitHub account](https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account).
 
 This documentation assumes you are fairly confident with git and GitHub. If that isn't the case, you may want to read some guides for [GitHub](https://docs.github.com/en/get-started/quickstart), [git](https://docs.github.com/en/get-started/using-git), and [pull requests](https://docs.github.com/en/pull-requests).
@@ -24,6 +20,10 @@ We ask for this so that the ownership in the license is clear and unambiguous, a
 
 There are a few things that you should do before you start working on a fix:
 
+[info]
+If you want to contribute changes to documentation, please read through the [contributing documentation](./documentation) page.
+[/info]
+
 ### Consider if your change should be its own module
 
 Not every feature belongs in the core modules - consider whether the change you want to make belongs in core or whether it would be more appropriate for you to [create a new module](/developer_guides/extending/modules/#create).
@@ -54,7 +54,7 @@ Please adjust the commands as appropriate for the version of Silverstripe CMS th
 
 ### Editing files directly on GitHub.com
 
-If you see a typo or another small fix that needs to be made, and you don't have an installation set up for contributions, you can edit files directly in the github.com web interface. Every file view on GitHub has an "edit this file" link.
+If you see a typo or another small fix that needs to be made, and you don't have an installation set up for contributions, you can edit files directly in the github.com web interface.
 
 After you have edited the file, GitHub will offer to create a pull request for you. This pull request will be reviewed along with other pull requests.
 
@@ -71,51 +71,27 @@ As we follow semantic versioning, we name the branches in repositories according
 
 If after reading this section you are still unsure what branch your pull request should go to, consider asking either in the GitHub issue that you address with your PR or in one of the various [community channels](https://www.silverstripe.org/community/).
 
+[hint]
+Refer to our [definition of public API](/project_governance/public_api/) for the following sections.
+[/hint]
+
+Any updates to third party dependencies in composer.json should aim to target the default branch for a minor release if possible. Targeting a patch release branch is acceptable if updating dependencies is required to fix a high impact or critical bug and is unlikely to result in regressions.
+
 #### For changes to public API or new/enhanced features
 
-If you are introducing new APIs, introducing new features, or enhancing an existing feature, you should generally use the default branch of the repository where you want to contribute to. That would usually target the next minor release of the module.
+If you are introducing new public API, introducing new features, or enhancing an existing feature, you should generally use the default branch of the repository where you want to contribute to. That would usually target the next minor release of the module.
 
 #### For bug fixes that don't introduce new API
 
-If you are fixing a bug that doesn't require API changes, use the highest patch release branch available for the lowest supported major release line the bug applies to. You can see the currently supported release lines for Silverstripe CMS on [the roadmap](https://www.silverstripe.org/software/roadmap/). You can find which major release lines of core and supported modules apply to that version by checking the relevant [/project_governance/supported_modules/](supported modules) page.
+If you are fixing a bug that doesn't require public API changes, use the highest patch release branch available for the lowest supported major release line the bug applies to. You can see the currently supported release lines for Silverstripe CMS on [the roadmap](https://www.silverstripe.org/software/roadmap/). You can find which major release lines of core and supported modules apply to that version by checking the relevant [supported modules](/project_governance/supported_modules/) page.
 
 For example, if your bug fix is applicable for Silverstripe CMS 4, and is for the `silverstripe/admin` module, you would target the `1.13` branch.
 
 #### For API breaking changes
 
-Do not make a pull request that includes a breaking change, including changing public API (described below), unless there is a major release branch ready to merge into.
+Do not make a pull request that includes a breaking change, including changing public API, unless there is a major release branch ready to merge into.
 e.g. if the latest stable release is `5.2.7`, the major release branch would be `6`.
 
-#### Definition of public API
-
-Silverstripe CMS public APIs explicitly include (unless excluded below):
-
-- **global** functions, constants, and variables
-- namespaces, classes, interfaces, enums, and traits
-- public and protected scope (including methods, properties and constants)
-- private static class properties (considered to be configuration variables)
-- yml configuration file structure and value types
-- extension hooks (e.g. `$this->extend('someExtensionHook'));`)
-
-Silverstripe CMS public APIs explicitly exclude:
-
-- private scope (with the exception for `private static` properties which aren't annotated with `@internal`)
-- all entities marked as `@internal`
-- yml configuration file default values
-- HTML, CSS, JavaScript (within reason), SQL, and anything else that is not PHP
-
-Other entities might be considered to be included or excluded from the public APIs on case-by-case basis based on how likely it is to cause problems during an upgrade.
-
-Any updates to third party dependencies in composer.json should aim to target the default branch for a minor release if possible. Targeting a patch release branch is acceptable if updating dependencies is required to fix a high impact or critical bug and is unlikely to result in regressions.
-
-API from third party dependencies may implicitly be incorporated into our definition of public API if:
-
-- they are defined as a parameter type for a supported method
-- they are defined as a return type for a supported method
-- they are extended by a Silverstripe CMS class.
-
-When defining a return type or a parameter type, it is preferable to use a more generic interface rather than a specific class. Third party dependencies that are used for internal purposes and are not explicitly exposed via the Silverstripe CMS public API are not covered by SemVer and maybe substituted without notice.
-
 ### Step 2: Install the project {#install-the-project}
 
 Install the project through composer. The process is described in detail in the [getting started](../getting_started/composer#contributing) docs.

en/06_Project_Governance/03_Maintainer_Guidelines.md

@@ -92,8 +92,8 @@ First and foremost rule of a maintainer is to collaborate with other maintainers
  * Ensure contributions have appropriate [test coverage](../developer_guides/testing), are documented, and pass our [coding conventions](/getting_started/coding_conventions)
  * Keep the codebase "releasable" at all times (check our [release process](release_process))
  * Follow [Semantic Versioning](code/#picking-the-right-version) by putting any changes into the correct branch
- * API changes and non-trivial features should not be merged into release branches. 
- * API changes on master should not be merged until they have the buy-in of at least two Core Committers (or better, through the [core mailing list](https://groups.google.com/forum/#!forum/silverstripe-dev))
+ * Public API changes and non-trivial features should not be merged into release branches. 
+ * Public API changes on master should not be merged until they have the buy-in of at least two Core Committers (or better, through the [core mailing list](https://groups.google.com/forum/#!forum/silverstripe-dev))
  * Be inclusive. Ensure a wide range of Silverstripe CMS developers can obtain an understanding of your code and docs, and you're not the only one who can maintain it.
  * Avoid `git push --force`, and be careful with your git remotes (no accidental pushes)
  * Use your own forks to create feature branches

en/06_Project_Governance/05_Major_release_policy.md

@@ -12,6 +12,10 @@ This policy applies to all [Silverstripe CMS commercially supported modules](htt
 
 Community modules are not covered by this policy. Modules in the `silverstripe` github organisation that are not commercially supported are updated on a best effort basis.
 
+[info]
+Refer to our [definition of public API](/project_governance/public_api/).
+[/info]
+
 ## General approach to major releases
 
 Silverstripe CMS aims to deliver regular major releases at predefined intervals with a clear support timeline. The key objective of this policy is to allow Silverstripe CMS project owners to plan major upgrades ahead of time.
@@ -26,7 +30,7 @@ The lifecycle for a Silverstripe CMS major release line is:
 
 Most of the changes shipped in a major release will:
 - upgrade third party dependencies
-- remove deprecated APIs and clean up ambiguous APIs
+- remove deprecated public API and clean up ambiguous API
 - implement architectural changes that can not reasonably be introduced in a minor release.
 
 At launch, major releases may contain new features not present in the previous major release line. However, this is a secondary concern. New features will usually ship in minor releases.
@@ -62,7 +66,7 @@ New major releases of Silverstripe CMS are tagged between April and June of odd
 ### Active development
 
 Once a major release is stable, it enters a period of active development. A major release in active development receives:
-- regular minor releases that ship new features and API in a backward compatible way
+- regular minor releases that ship new features and public API in a backward compatible way
 - regular patches for bugs at all impact levels
 - security patches for all vulnerabilities.
 
@@ -80,7 +84,7 @@ A major release line in the *bug and security fixes* phase receives:
 
 A major release line in the *bug and security fixes* phase does **not** receive:
 - new feature
-- new APIs
+- new public API
 - new minor releases.
 
 A major release line stays in the *bug and security fixes* phase for 1 year.

en/06_Project_Governance/06_Minor_release_policy.md

@@ -10,7 +10,11 @@ This policy complements the [Silverstripe CMS Major release policy](major_releas
 
 Note that the release cadence and pre-release time frame are indicative only. We may alter those in response to external constraints.
 
-Our minor release policy is more flexible because minor release upgrades are more straightforward to manage than major release upgrades. 
+Our minor release policy is more flexible because minor release upgrades are more straightforward to manage than major release upgrades.
+
+[info]
+Refer to our [definition of public API](/project_governance/public_api/).
+[/info]
 
 ## Scope of the policy
 
@@ -20,7 +24,7 @@ Community modules are not covered by this policy. Modules in the `silverstripe`
 
 ## Upgrading to a new minor release
 
-Silverstripe CMS follows [semantic versioning](https://semver.org/). Silverstripe CMS minor releases deliver new features and new APIs in a backward compatible way.
+Silverstripe CMS follows [semantic versioning](https://semver.org/). Silverstripe CMS minor releases deliver new features and new public API in a backward compatible way.
 
 ## Minor release cadence
 
@@ -30,7 +34,7 @@ Silverstripe CMS aims to ship a new minor releases every 6 months for the major
 
 Silverstripe CMS does not usually tag alpha releases for minor releases.
 
-Approximately 6 weeks prior to the anticipated stable minor release, a beta minor release is published. Once a beta release is tagged, any new feature or API that didn't make it to the beta should be targeted to the follow up minor release. This allows the CMS development team to perform a regression test on the beta release with confidence that no additional regressions will be introduced before the stable release.
+Approximately 6 weeks prior to the anticipated stable minor release, a beta minor release is published. Once a beta release is tagged, any new feature or public API that didn't make it to the beta should be targeted to the follow up minor release. This allows the CMS development team to perform a regression test on the beta release with confidence that no additional regressions will be introduced before the stable release.
 
 Approximately 2 weeks prior to the anticipated stable minor release, a release candidate is tagged. Once a release candidate is tagged, only critical impact bug fixes can be added to the release. The release candidate is sent to an external auditor for a security review. Any security patches which will be included in the stable release are also sent to the auditor.
 
@@ -47,12 +51,12 @@ The minor release support timeline follows similar phases to those of a major re
 A Silverstripe CMS minor release line enters the *bug and security fixes* phase once it is tagged *stable*.
 
 A minor release in the *bug and security fixes* phase receives:
-- bugfixes that do not change existing APIs
+- bugfixes that do not change existing public API
 - security patches for vulnerabilities at all impact levels.
 
 It does **not** receive:
 - new features
-- new APIs.
+- new public API.
 
 A minor release line stays in the *bug and security fixes* phase until a follow up minor release is tagged.
 

en/06_Project_Governance/07_Supported_Modules.md

@@ -5,7 +5,7 @@ description: Modules which are commercially supported by Silverstripe
 
 # Commercially supported modules
 
-Silverstripe CMS ships modules that receive commercial support. Commercially supported modules receive regular updates to work with the latest Silverstripe CMS release. Their APIs conform to [semantic versioning](https://semver.org/). They are covered by:
+Silverstripe CMS ships modules that receive commercial support. Commercially supported modules receive regular updates to work with the latest Silverstripe CMS release. Their [public API](/project_governance/public_api/) conforms to [semantic versioning](https://semver.org/). They are covered by:
 
 - our [security release process](/contributing/managing_security_issues) and
 - our [major release policy](major_release_policy).
@@ -146,6 +146,6 @@ The following two NPM packages are also supported because they are required to b
 
 ## Other modules in the "silverstripe" namespace
 
-There are other modules hosted under the _silverstripe_ Packagist namespace. These modules are maintained on a best effort basis. They are not guaranteed to go through regular regression testing. Their APIs may be more fluid than supported modules. They maybe more experimental or may not receive the same level of care as supported modules.
+There are other modules hosted under the _silverstripe_ Packagist namespace. These modules are maintained on a best effort basis. They are not guaranteed to go through regular regression testing. Their public API may be more fluid than supported modules. They maybe more experimental or may not receive the same level of care as supported modules.
 
 These modules can still be used in Silverstripe CMS projects, but should be considered as community modules.

en/06_Project_Governance/08_Public_API.md

@@ -0,0 +1,46 @@
+---
+title: Definition of Public API
+summary: A definition of what we consider to be "public API" which is protected by semantic versioning
+icon: code
+---
+
+# Definition of public API
+
+The following is a definition of what we consider to be "public API". Public API is protected by semantic versioning.
+
+New public API will not be introduced in patches, but can be introduced in minor and major releases.
+
+Existing public API will not be removed or altered in patches or minor releases, but can be removed or altered in major releases.
+
+## Explicitly included
+
+These are explicitly included in our definition of public API (unless excluded below):
+
+* **global** functions, constants, and variables
+* namespaces, classes, interfaces, enums, and traits
+* public and protected scope (including methods, properties and constants)
+* private static class property declarations (considered to be configuration variables)
+* configuration default values (in yml files and in private statics)
+* yml configuration file and fragment names (see [yml configuration syntax](/developer_guides/configuration/configuration/#syntax))
+* extension hooks (e.g. `$this->extend('someExtensionHook', $someVariable);`)
+
+## Explicitly excluded
+
+These are explicitly _not_ public API:
+
+* private scope (with the exception for `private static` properties which aren't annotated with `@internal`)
+* all entities marked as `@internal`
+* yml configuration in recipes
+* HTML, CSS, JavaScript (within reason), SQL, and anything else that is not PHP
+
+## Implicit or undefined scenarios
+
+Other entities might be considered to be included or excluded from the public API on case-by-case basis based on how likely it is to cause problems during an upgrade.
+
+API from third party dependencies may implicitly be incorporated into our definition of public API if:
+
+* they are defined as a parameter type for a supported method
+* they are defined as a return type for a supported method
+* they are extended by a Silverstripe CMS class.
+
+When defining a return type or a parameter type, it is preferable to use a more generic interface rather than a specific class. Third party dependencies that are used for internal purposes and are not explicitly exposed via the Silverstripe CMS public API are not covered by semantic versioning and maybe substituted without notice.