Merge branch '4' into 5.1

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

@@ -173,7 +173,7 @@ which the Silverstripe CMS project applies to the modules it creates and maintai
  * All Composer dependencies are bound to a single major release (e.g. `^5.0` not `>=5` or `*`) unless there are obvious reasons not to for some specific dependency.
  * There is a level of test coverage.
  * Uses strong typing where appropriate.
- * A clear public API documented in the docblock tags.
+ * A clear [public API](/project_governance/public_api/) documented in the docblock tags.
    * If parameters and return values don't need additional description and are strongly typed, these should be ommitted from the docblock.
  * Code follows [PSR-1](https://www.php-fig.org/psr/psr-1/) and [PSR-2](https://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.

en/02_Developer_Guides/09_Security/05_Secure_Coding.md

@@ -654,6 +654,13 @@ server IPs using the SS_TRUSTED_PROXY_IPS define in your `.env`.
 SS_TRUSTED_PROXY_IPS="127.0.0.1,192.168.0.1"
 ```
 
+You can also whitelist subnets in CIDR notation if you don't know the exact IP of a trusted proxy.
+For example, some cloud provider load balancers don't have fixed IPs.
+
+```
+SS_TRUSTED_PROXY_IPS="10.10.0.0/24,10.10.1.0/24,10.10.2.0/24"
+```
+
 If you wish to change the headers that are used to find the proxy information, you should reconfigure the
 TrustedProxyMiddleware service:
 
@@ -676,7 +683,7 @@ At the same time, you'll also need to define which headers you trust from these
 
 If there is no proxy server, 'none' can be used to distrust all clients.
 If only trusted servers will make requests then you can use '*' to trust all clients.
-Otherwise a comma separated list of individual IP addresses should be declared.
+Otherwise a comma separated list of individual IP addresses (or subnets in CIDR notation) should be declared.
 
 This behaviour is enabled whenever `SS_TRUSTED_PROXY_IPS` is defined, or if the
 `BlockUntrustedIPs` environment variable is declared. It is advisable to include the

en/05_Contributing/00_Issues_and_Bugs.md

@@ -19,7 +19,11 @@ Silverstripe CMS uses [GitHub](https://github.com/) to manage bug reports. If yo
 want to report a bug, you will need to [create a GitHub account](https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account)
 and log in.
 
-Before submitting a bug:
+[warning]
+We don't provide support through GitHub issues. If you're having trouble using or developing with Silverstripe CMS but you don't think your problem is a bug, please ask for assistance in our [community channels](https://www.silverstripe.org/community).
+[/warning]
+
+### Before submitting a bug
 
  * Ask for assistance in our [community channels](https://www.silverstripe.org/community) if you're unsure if it's really a bug.
  * Search for similar, existing issues.
@@ -28,7 +32,7 @@ Before submitting a bug:
  * Is this a security issue? Please follow our [security reporting guidelines](#reporting-security-issues) below.
  * Try to reproduce your issue on a [clean installation](/getting_started/composer#create-a-new-site) to rule out bugs in your own code.
 
-If the issue does look like a new bug:
+### If the issue does look like a new bug
 
  * Create an issue on the right module repository in GitHub
    * If you are unsure, [create an issue](https://github.com/silverstripe/silverstripe-framework/issues/new) on the the "framework" repository.

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/05_Contributing/06_Documentation.md

@@ -163,19 +163,19 @@ Relative documentation links are prefixed with `./` for pages in the same direct
 
 Absolute documentation links are preferred for pages which aren't in the same directory or one level up. The language and version number are ommitted. For example `[managing lists](/developer_guides/model/lists/)` becomes [managing lists](/developer_guides/model/lists/).
 
-#### Links to API documentation
+### Links to API documentation
 
 API documentation is linked in a special way. Give some examples for classes, methods, properties.
 
-For classes, interfaces, traits, and enums:
+#### For classes, interfaces, traits, and enums
 
 ``[`Form`](api:SilverStripe\Forms\Form)`` will become [`Form`](api:SilverStripe\Forms\Form), and will link to the API documentation for the `SilverStripe\Forms\Form` class.
 
-For methods:
+#### For methods
 
 ``[`Form::makeReadonly()`](api:SilverStripe\Forms\Form::makeReadonly())`` will become [`Form::makeReadonly()`](api:SilverStripe\Forms\Form::makeReadonly()), and will link to the API documentation for the `makeReadonly()` method in the `SilverStripe\Forms\Form` class.
 
-For properties, including configuration properties:
+#### For properties, including configuration properties
 
 ``[`Form->casting`](api:SilverStripe\Forms\Form->casting)`` will become [`Form->casting`](api:SilverStripe\Forms\Form->casting), and will link to the API documentation for the `casting` property in the `SilverStripe\Forms\Form` class.
 

en/05_Contributing/07_Translations.md

@@ -1,5 +1,5 @@
 ---
-title: Translations
+title: Contributing Translations
 summary: Translate interface components like button labels into multiple languages.
 icon: globe
 ---
@@ -8,7 +8,7 @@ icon: globe
 
 The content for UI elements (button labels, field titles, etc) and instruction texts shown in the CMS and elsewhere is
 stored in yaml and JavaScript files (see [i18n](/developer_guides/i18n)). These get
-uploaded to [transifex](https://explore.transifex.com/silverstripe/) to be edited online.
+uploaded to [transifex](https://transifex.com) to be edited online.
 
 Silverstripe CMS is already translated in over 60 languages, and we're
 relying on native speakers to keep these up to date, and of course add new languages.
@@ -21,9 +21,9 @@ Please [register a free translator account](https://app.transifex.com/signup/ope
 
 ## The online translation tool
 
-We provide a GUI for translations through [transifex.com](https://transifex.com). If you don't have an account yet,
+We provide a GUI for translations through [transifex.com](https://app.transifex.com/silverstripe/). If you don't have an account yet,
 please follow the links there to sign up.  Select a project from the
-[list of translatable modules](https://app.transifex.com/silverstripe/) and start translating online!
+[list of translatable modules](https://explore.transifex.com/silverstripe/) and start translating online!
 
 If you need help learning how to edit translations in transifex, check out [transifex's documentation](https://help.transifex.com/).
 
@@ -35,7 +35,7 @@ If a core or supported module is not listed on Transifex, usually that means it
 If you find a core or supported module which has strings that can be (or should be able to be) translated, please
 [raise an issue on GitHub](./issues_and_bugs) for that module.
 
-### How do I translate substituted strings? (e.g. '%s' or '{my-variable}')
+### How do I translate substituted strings? (e.g. `%s` or `{my-variable}`)
 
 You don't have to - if the english string reads 'Hello %s', your german translation would be 'Hallo %s'. Strings
 prefixed by a percentage-sign are automatically replaced by silverstripe with dynamic content. See

en/05_Contributing/15_Triage_Resources.md

@@ -6,10 +6,41 @@ icon: users
 
 # Triage and peer review
 
-This page collates common resources that maintainers can use to efficiently and consistently manage incoming issues and
-PRs.
+Triage and peer review are important processes for getting changes made and merged.
 
-## Merge Checklist
+If you are involved with triage of Silverstripe CMS core and supported modules, regularly check the repository for new issues or use the ["Untriaged" filter](https://silverstripe-github-issues.now.sh/?mode=untriaged) in our cross-repository issue tracker.
+
+You can also optionally subscribe to the repository via [GitHub watch functionality](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).
+
+[hint]
+When performing these tasks, make sure to adhere to the [code of conduct](/project_governance/code_of_conduct/) and [maintainer guidelines](/project_governance/maintainer_guidelines/#guidelines).
+[/hint]
+
+## How to triage
+
+Triaging issues involves review, applying labels, and closing invalid issues/PRs.
+
+How to do it
+
+* Read the docs about [how we use labels](./issues_and_bugs/#labels), and apply the relevant labels to any untriaged issues
+* Request follow-up information if you can't reproduce the issue based on the information that has been provided
+* Close any issues that seem like spam, are duplicates, are requesting support rather than reporting a bug, are feature requests that the reporter doesn't intend to implement, etc
+  * Make sure to explain why you are closing the issue. There are some [canned responses](#canned-responses) that you can use
+* For any issues you add the "impact/critical" label to, bring this to the attention of the Core Committers and the CMS Squad
+* If unsure about anything, it’s usually good to ask other maintainers for their opinions (on Slack or via mentioning them directly on GitHub)
+
+## How to review pull requests
+
+Reviewing and merging PRs is one of the most critical responsibilities, which often requires a lot of effort and scrutiny.
+
+Bad PRs may contain technical debt, provide problems in the future and require extra attention and time from the maintainers. It is usually better not to merge at all, rather than merge half-ready or poorly written code. Especially if a PR comes from a non-maintainer who’s not responsible for taking care of the feature later on. On the other hand, the nature of Open Source implies access to resources of the community, so it’s important to make sure we don’t close the doors for people willing to spend their time and brain energy.
+
+How to do it
+
+* Follow the [merge checklist](#merge-checklist). You may even post it straight on GitHub so the contributor sees the PR progress
+* If the author doesn't respond for several weeks you may choose take the PR over and push it forward yourself by adding your own commits to their branch - in that case, you become the developer and someone else will need to review the pull request when you are done. Otherwise, it’s fine to close the PR if there has been no response and you don't want to take it over yourself.
+
+### Merge Checklist
 
 This list helps to ensure that PRs are in a good state before merging. Ideally it should be applied to the PR upon
 initial triage, so that the contributor can check items off prior to the reviewer digging in. Some items may not be
@@ -52,6 +83,13 @@ progress the work or respond to any outstanding feedback.
 > It seems like there's going to be no further activity on this pull request, so we’ve closed it for now. Please open a
 > new pull-request if you want to re-approach this work, or for anything else you think could be fixed or improved.
 
+### Support Issue raised
+
+**Context:** We don't provide support through GitHub issues. If an issue is created that is requested support rather than reporting a bug, we'll close the issue and link to the community channels.
+
+> We don't provide support through GitHub issues. The problems you're experiencing don't seem to be a result of bugs in Silverstripe CMS core or supported modules, so
+> I'm going to close this issue. Please ask for support in our [community channels](https://www.silverstripe.org/community).
+
 ### Enhancement Issue raised
 
 **Context:** See the notes about feature requests in the [bug report](./issues_and_bugs/#feature-requests) and [contributing code](./code/#make-or-find-a-github-issue) pages for details.