diff --git a/en/02_Developer_Guides/05_Extending/00_Modules.md b/en/02_Developer_Guides/05_Extending/00_Modules.md index da4273d4a..a7a84b76b 100644 --- a/en/02_Developer_Guides/05_Extending/00_Modules.md +++ b/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. diff --git a/en/02_Developer_Guides/09_Security/05_Secure_Coding.md b/en/02_Developer_Guides/09_Security/05_Secure_Coding.md index c73d9ef1d..6e1bd6b05 100644 --- a/en/02_Developer_Guides/09_Security/05_Secure_Coding.md +++ b/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 diff --git a/en/05_Contributing/00_Issues_and_Bugs.md b/en/05_Contributing/00_Issues_and_Bugs.md index 5bd0a5ee5..e76ad416e 100644 --- a/en/05_Contributing/00_Issues_and_Bugs.md +++ b/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. diff --git a/en/05_Contributing/01_Code.md b/en/05_Contributing/01_Code.md index 09518073c..363fa9eb4 100644 --- a/en/05_Contributing/01_Code.md +++ b/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. diff --git a/en/05_Contributing/06_Documentation.md b/en/05_Contributing/06_Documentation.md index 65dc3755c..37dd17b3e 100644 --- a/en/05_Contributing/06_Documentation.md +++ b/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. diff --git a/en/05_Contributing/07_Translations.md b/en/05_Contributing/07_Translations.md index 65ab70c1b..0c3ccdca3 100644 --- a/en/05_Contributing/07_Translations.md +++ b/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 diff --git a/en/05_Contributing/15_Triage_Resources.md b/en/05_Contributing/15_Triage_Resources.md index 28ec20a54..70f3ee7f2 100644 --- a/en/05_Contributing/15_Triage_Resources.md +++ b/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. diff --git a/en/06_Project_Governance/03_Maintainer_Guidelines.md b/en/06_Project_Governance/03_Maintainer_Guidelines.md index 17c549de6..8d6454b82 100644 --- a/en/06_Project_Governance/03_Maintainer_Guidelines.md +++ b/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”](/#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,33 +26,15 @@ 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. - - -### Triage +focus on core development work and are full-time employees of Silverstripe. -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 @@ -80,47 +42,17 @@ 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) - - -### How to triage - -Triaging issues and pull requests involves review, applying labels, as well as closing invalid submissions. - -Applying [labels](./issues_and_bugs/#labels) is the main mechanism used to escalate critical and high impact issues, give feedback to the community, or peer review a PR and let other maintainers know it is “good to be merged on green CI tests”. - - -How to do it - - 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. - - Ideally subscribe to the repository via [GitHub Watch](https://docs.github.com/en/free-pro-team@latest/github/managing-subscriptions-and-notifications-on-github/viewing-your-subscriptions#configuring-your-watch-settings-for-an-individual-repository) functionality - - Read the docs about [how we use labels](./issues_and_bugs/#labels) - - 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 - -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. So, 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](./triage_resources/#merge-checklist). You may even post it straight on GitHub so the contributor sees the PR progress - - Ensure you’re familiar with the module own conventions (explained in README or CONTRIBUTING files). - - If the author disappears you may either take the PR over and push it forward yourself by adding your own commits to their branch. Otherwise, it’s fine to close their PR if they don’t respond for over several weeks. +* 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) diff --git a/en/06_Project_Governance/05_Major_release_policy.md b/en/06_Project_Governance/05_Major_release_policy.md index c26b3f70d..92a0803f9 100644 --- a/en/06_Project_Governance/05_Major_release_policy.md +++ b/en/06_Project_Governance/05_Major_release_policy.md @@ -12,6 +12,10 @@ This policy applies to all [Silverstripe CMS commercially supported modules](/pr 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. diff --git a/en/06_Project_Governance/06_Minor_release_policy.md b/en/06_Project_Governance/06_Minor_release_policy.md index 3cfc63311..cd3c4ac20 100644 --- a/en/06_Project_Governance/06_Minor_release_policy.md +++ b/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. diff --git a/en/06_Project_Governance/07_Supported_Modules.md b/en/06_Project_Governance/07_Supported_Modules.md index cac7c01d7..dca34006e 100644 --- a/en/06_Project_Governance/07_Supported_Modules.md +++ b/en/06_Project_Governance/07_Supported_Modules.md @@ -5,14 +5,21 @@ 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: -- our [security release process](/contributing/managing_security_issues) and +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). These modules will be supported for the lifetime of Silverstripe CMS 5 in the provided major versions. ## Core Silverstripe CMS modules +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://packagist.org/packages/silverstripe/recipe-core) +- [silverstripe/recipe-cms](https://packagist.org/packages/silverstripe/recipe-cms) +- [silverstripe/installer](https://packagist.org/packages/silverstripe/installer) + These modules provide the core Silverstripe CMS experience. Most Silverstripe CMS projects should install all of them. Core Module | Supported major release line @@ -103,11 +110,12 @@ Supported PHP Module | Supported versions ## Supported NPM packages The following two NPM packages are also supported because they are required to build the UI of Silverstripe CMS 5: + - [@silverstripe/webpack-config](https://www.npmjs.com/package/@silverstripe/webpack-config) - [@silverstripe/eslint-config](https://www.npmjs.com/package/@silverstripe/eslint-config) ## 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. \ No newline at end of file +These modules can still be used in Silverstripe CMS projects, but should be considered as community modules. diff --git a/en/06_Project_Governance/08_Public_API.md b/en/06_Project_Governance/08_Public_API.md new file mode 100644 index 000000000..1fc5c44db --- /dev/null +++ b/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. \ No newline at end of file diff --git a/en/_images/contributing/docs-commit-message.png b/en/_images/contributing/docs-commit-message.png index a2ebbc757..754972f57 100644 Binary files a/en/_images/contributing/docs-commit-message.png and b/en/_images/contributing/docs-commit-message.png differ diff --git a/en/_images/contributing/docs-use-correct-branch.png b/en/_images/contributing/docs-use-correct-branch.png index 440699641..ae3f65358 100644 Binary files a/en/_images/contributing/docs-use-correct-branch.png and b/en/_images/contributing/docs-use-correct-branch.png differ