Merge branch '4.13' into 4

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

@@ -1,43 +1,23 @@
 ---
 title: Maintainer guidelines
 summary: Cheat sheet for module maintainers
-iconBrand: wpforms
+icon: clipboard-list
 ---
 
-
 # Maintainer Guidelines
 
-This doc outlines expectations on maintainers of Silverstripe Core. It also forms the default expectations for maintainers of Supported Modules, unless more specific contribution guidelines are available for a module.
+This doc outlines expectations on maintainers of Silverstripe CMS. It also forms the default expectations for maintainers of [supported modules](./supported_modules/), unless more specific contribution guidelines are available for a module.
 
-Module maintainers are people taking care of the repositories, CI, documentation, source code, conventions, community communications, issue triage, and release management.
+Module maintainers are people taking care of the repositories, CI, documentation, source code, conventions, community communications, peer review, issue triage, and release management.
 
 One of the most important maintainer responsibilities is to collaborate with other maintainers. Another important role is to facilitate community contributions (such as issue reports and pull requests).
 
 [note]
-A lot of extra information is available in Silverstripe CMS documentation section [“Contributing to Silverstripe”](./).
+A lot of extra information is available in the [Contributing](/contributing/) documentation.
 All maintainers should be familiar with those docs as they explain many details about how we work.
 [/note]
 
-
-## What is Silverstripe Core
-
-Silverstripe CMS is powered by a system of components in the form of Composer packages. These packages will be categorised as either a _module_ or a _recipe_.
-
-The "core" of Silverstripe refers to the module packages owned by the "silverstripe" Packagist vendor that fall under one of the following recipes:
-
-* [silverstripe/recipe-core](https://github.com/silverstripe/recipe-cms)
-* [silverstripe/recipe-cms](https://github.com/silverstripe/recipe-cms)
-* [silverstripe/installer](https://github.com/silverstripe/silverstripe-installer)
-
-## What are Supported Modules
-
-In addition to Silverstripe Core, there are many [Supported Modules](https://www.silverstripe.org/software/addons/supported-modules-definition/)
-which have the backing of Silverstripe Ltd. While it's a good idea to apply the rules outlined in this document,
-work on these modules is guided by the 
-[Supported Modules Standard](https://www.silverstripe.org/software/addons/supported-modules-definition/).
-Commit access in Supported Modules is handled by agreement of the repository maintainers,
-or any additional guidelines outlined via `README` and `CONTRIBUTING` files.
-
+Refer to the [triage and peer review](/contributing/triage_resources/) for information about how those tasks are performed.
 
 ## Maintainer Roles
 
@@ -46,55 +26,33 @@ or any additional guidelines outlined via `README` and `CONTRIBUTING` files.
 The people looking after the Silverstripe Core modules.
 See the details on the [Core Committers](./core_committers) page.
 
-
-### Contributing Committers
+### CMS Squad
 
 Beyond the Core Committer role, there can be individuals which
-focus on core development work - typically sponsored through full-time product development roles by Silverstripe Ltd.
-These Contributing Committers require write access to core repositories to maintain their pace,
-often working alongside Core Committers. They are guided by additional rules:
-
- * Contributing Committers have write access to core repositories in order to work effectively with Github issues. They are expected to use those permissions with good judgement regarding merges of pull requests.
- * Complex or impactful changes need to be reviewed and approved by one or more Core Committers. This includes any additions, removals or changes to commonly used APIs. If that's not possible in the team, ping `@silverstripe/core-team` to get other Core Committers involved.
- * For these complex or impactful changes, Core Committers should be given 1-2 working days to review. Ideally at this point, the API has already been agreed on through issue comments outlining the planned work (see [RFC Process](request_for_comment]).
- * More straightforward changes (e.g. documentation, styling) or areas which require quite specialised expertise (e.g. React) that's less available through most Core Committers can be approved or merged by team members who aren't Core Committers.
- * Self-merges should be avoided, but are preferable to having work go stale or forcing other team members to waste time by context switching into a complex review (e.g. because the original reviewer went on leave). Any self-merge should be accompanied by a comment why this couldn't be handled in another way, and a (preferably written) approval from another team member.
-
-This role may be granted by any Core Committer,
-who should give other Core Committers an opportunity to weigh in on the decision.
-
+focus on core development work and are full-time employees of Silverstripe.
 
-### Triage
-
-Triage of issues and pull request is an important activity: Reviewing issues, adding labels,
-closing stale issues, etc. This does not require write access to the repository as a "Contributing Committer".
-This is a great way for active community members to help out, and start a path towards becoming a Core Committer.
-
-Triage roles may be granted by any Core Committer,
-who should give other Core Committers an opportunity to weigh in on the decision.
+The CMS Squad require write access to core repositories to maintain their pace,
+often working alongside Core Committers.
 
+CMS Squad members have write access to core repositories in order to work effectively with GitHub issues. They are expected to use those permissions with good judgement for merging pull requests.
 
 ## Guidelines
 
 With great power (write access) comes great responsibility.
 
 First and foremost rule of a maintainer is to collaborate with other maintainers. Follow the house rules and remember that others also care about the modules they maintain.
 
-
 ### House rules overview
 
- * Be friendly, encouraging and constructive towards other community members
- * Frequently review pull requests and new issues (in particular, respond quickly to @mentions)
- * Treat issues according to our [issue guidelines](issues_and_bugs), and use the [triage resources](triage_resources)
- * Don't commit directly to a release branch, raise pull requests instead (except trivial fixes)
- * Only merge code you have tested and fully understand. If in doubt, ask for a second opinion.
- * Follow the [Supported Modules Standard](https://www.silverstripe.org/software/addons/supported-modules-definition/)
- * 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))
- * 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
- * We release using the standard process. See the [Making a Silverstripe CMS Core Release](making_a_silverstripe_core_release)
+* Be friendly, encouraging and constructive towards other community members
+* Frequently review pull requests and new issues (in particular, respond quickly to @mentions)
+* Treat issues according to our [issue guidelines](/contributing/issues_and_bugs/), and use the [triage resources](/contributing/triage_resources/)
+* Don't commit directly to existing branches, raise pull requests instead
+* Use forks to create feature branches for pull requests
+* Only merge code you have tested and fully understand. If in doubt, ask for a second opinion.
+* Follow the [Supported Modules Standard](https://www.silverstripe.org/software/addons/supported-modules-definition/)
+* Ensure contributions have appropriate [test coverage](/developer_guides/testing/), are documented, and adhere to our [coding conventions](/getting_started/coding_conventions/)
+* Keep the codebase "releasable" at all times (check our [release process](/contributing/release_process/))
+* Follow [Semantic Versioning](/contributing/code/#picking-the-right-version) by putting any changes into the correct branch
+* 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)

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.