diff --git a/en/02_Developer_Guides/19_GraphQL/04_security_and_best_practices/05_recursive_or_complex_queries.md b/en/02_Developer_Guides/19_GraphQL/04_security_and_best_practices/05_recursive_or_complex_queries.md new file mode 100644 index 000000000..814f12dda --- /dev/null +++ b/en/02_Developer_Guides/19_GraphQL/04_security_and_best_practices/05_recursive_or_complex_queries.md @@ -0,0 +1,50 @@ +--- +title: Recursive or complex queries +summary: Protecting against potentially malicious queries +--- + +# Security & best practices + +[CHILDREN asList] + +## Recursive or complex queries + +GraphQL schemas can contain recursive types and circular dependencies. Recursive or overly complex queries can take up a lot of resources, +and could have a high impact on server performance and even result in a denial of service if not handled carefully. + +Before parsing queries, if a query is found to have more than 500 nodes, it is rejected. While executing queries there is a default query depth limit of 15 for all schemas with no complexity limit. + +You can customise the node limit and query depth and complexity limits by setting the following configuration: + +**app/_config/graphql.yml** + +```yaml +--- +After: 'graphql-schema-global' +--- +SilverStripe\GraphQL\Schema\Schema: + schemas: + '*': + config: + max_query_nodes: 250 # default 500 + max_query_depth: 20 # default 15 + max_query_complexity: 100 # default unlimited +``` + +[info] +For calculating the query complexity, every field in the query gets a default score 1 (including ObjectType nodes). Total complexity of the query is the sum of all field scores. +[/info] + +You can also configure these settings for individual schemas. This allows you to fine-tune the security of your custom public-facing schema without affecting the security of the schema used in the CMS. To do so, either replace `'*'` with the name of your schema in the yaml configuration above, or set the values under the `config` key for your schema using preferred file structure as defined in [configuring your schema](../getting_started/configuring_your_schema/). For example: + +**app/_graphql/config.yml** + +```yaml +max_query_nodes: 250 +max_query_depth: 20 +max_query_complexity: 100 +``` + +### Further reading + +[CHILDREN] diff --git a/en/05_Contributing/00_Issues_and_Bugs.md b/en/05_Contributing/00_Issues_and_Bugs.md index 31686872a..5bd0a5ee5 100644 --- a/en/05_Contributing/00_Issues_and_Bugs.md +++ b/en/05_Contributing/00_Issues_and_Bugs.md @@ -1,96 +1,110 @@ --- -title: Bug Reports -summary: Report bugs or problems with SilverStripe, feature requests or other issues. +title: Issues and Bug Reports +summary: Report bugs or problems with Silverstripe CMS, feature requests or other issues. icon: bug --- -# Contributing Issues and Opinions +# Issues and Bug Reports ## Reporting Bugs +[alert] +If you think you've found a security issue, please use [the specific process](#reporting-security-issues) for those. Do _not_ raise a security issue in GitHub. +[/alert] + If you have discovered a bug in Silverstripe CMS, we'd be glad to hear about it - well written bug reports can be half of the solution already! +Silverstripe CMS uses [GitHub](https://github.com/) to manage bug reports. If you +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: * 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 tickets. + * Search for similar, existing issues. You can [list all issues across modules](https://www.silverstripe.org/community/contributing-to-silverstripe/github-all-core-issues), then add your search phrase at the start of the existing search filters (for example [all issues with label "type/ux"](https://www.silverstripe.org/community/contributing-to-silverstripe/github-all-open-ux-issues)) - * Is this a security issue? Please follow our separate reporting guidelines below. - * Which modules does this issue belong to? Each one has its own issue tracker. - If you are unsure, [create an issue](https://github.com/silverstripe/silverstripe-framework/issues/new) on the the "framework" repository. - * Note that [documentation issues](https://github.com/silverstripe/developer-docs/issues) are tracked in the "developer-docs" repository. - * Try to reproduce your issue on a [clean installation](/getting_started/composer#using-development-versions), maybe the bug has already been fixed on an unreleased branch? - * The bugtracker is not the place to discuss enhancements, please use - the ["feature ideas" forum category](https://forum.silverstripe.org/c/feature-ideas) and our [community channels](https://www.silverstripe.org/community). - Only log enhancement tickets if they gather a large interest in the community - and the enhancement is likely to be implemented in the next couple of months. + * 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: * Create an issue on the right module repository in GitHub - * Describe the steps required to reproduce your issue, and the expected outcome. Unit tests, screenshots and screencasts can help here. - * Describe your environment as detailed as possible: SilverStripe version, Browser, PHP version, Operating System, any installed SilverStripe modules. - * *(optional)* [Submit a pull request](/contributing/code/#step-by-step-from-forking-to-sending-the-pull-request) which fixes the issue. - -Lastly, don't get your hopes up too high. Unless your issue is a blocker -affecting a large number of users, don't expect SilverStripe developers to jump -onto it right way. Your issue is a starting point where others with the same -problem can collaborate with you to develop a fix. + * If you are unsure, [create an issue](https://github.com/silverstripe/silverstripe-framework/issues/new) on the the "framework" repository. + * Note that [documentation issues](https://github.com/silverstripe/developer-docs/issues) are tracked in the "developer-docs" repository. + * Describe the steps required to reproduce your issue, and the expected outcome. Example code, screenshots, and videos can help here. + Be as clear as you can, but don't miss any steps out. Simply saying "create a page" is less useful than guiding us through the steps you're taking to create a page, for example. + * If the bug is too complex to reproduce with some short code samples, please reproduce it in a public repository and provide a link to the repository along with steps for setting up and reproducing the bug using that repository. + A repository like this should only contain code that is required to set up and reproduce the bug. + * Describe your environment in as much detail as possible. Include the versions of relevant modules, the PHP version, webserver, and operating system used to run the project, the browser(s) you see the issue in, etc. + * If part of the bug includes an error or exception, please provide a full stack trace. Be wary that stack traces may contain sensitive information, and if that is the case, be sure to redact them prior to posting your stack trace. + * You are strongly encouraged to [submit a pull request](/contributing/code/#step-by-step-from-forking-to-sending-the-pull-request) which fixes the issue. Bug reports which are accompanied with a pull request are a lot more likely to be resolved quickly. + +Lastly, don't get your hopes up too high. Unless your issue is a blocker +affecting a large number of users, don't expect Silverstripe developers to jump +onto it right way. Your issue is a starting point where others with the same +problem can collaborate with you to develop a fix. If this bug is a blocker +for you, then [submitting a pull request](/contributing/code/#step-by-step-from-forking-to-sending-the-pull-request) +is the best way to ensure it gets fixed. ## Feature Requests [warning] -Please don't file "feature requests" as Github issues. If there's a new feature -you'd like to see in SilverStripe, you either need to write it yourself (and -[submit a pull request](/contributing/code/#step-by-step-from-forking-to-sending-the-pull-request) or convince somebody else to -write it for you. Any "wishlist" type issues without code attached can be +Please don't file feature requests as Github issues. If there's a new feature +you'd like to see in Silverstripe CMS, you either need to write it yourself (and +[submit a pull request](/contributing/code/#step-by-step-from-forking-to-sending-the-pull-request)) or convince somebody else to +write it for you. Any "wishlist" type issues without code attached can be expected to be closed as soon as they're reviewed. [/warning] -In order to gain interest and feedback in your feature, we encourage you to +In order to gain interest and feedback in your feature, we encourage you to present it to the community through the [community channels](https://www.silverstripe.org/community). ## Reporting Security Issues +[warning] If you think a bug may have security implications, do not create a GitHub issue for it. This may lead to a zero-day vulnerability. +[/warning] -Report potential security issues to [security@silverstripe.org](mailto:security@silverstripe.org). -See our "[Release Process](/contributing/release_process/#security-releases)" documentation for more info, and -read our guide on [how to write secure code](/developer_guides/security/secure_coding/). +Report potential security issues to [security@silverstripe.org](mailto:security@silverstripe.org). Emails sent to that address are +forwarded to a private mailing list and kick off a specific security process. -Silverstripe CMS does not operate a *bug bounty* program. +If you have any doubts or are unsure whether the bug you've found has security implications or not, please err on the side of caution +and email us about it. -Review our [Managing Security Guidelines](managing_security_issues) guidelines to understand what happens once a vulnerability is reported. +Review our [Managing Security Issues](managing_security_issues) process to understand what happens once a vulnerability is reported. Silverstripe CMS aims to ship security patches at pre-defined intervals when those issues are not actively exploited in the wild. - Review the [Security patch windows](../Project_Governance/Minor_release_policy#security-patch-windows) section of our minor release policy for more details. -## Sharing your Opinion - -* [forum.silverstripe.org](https://forum.silverstripe.org): Forums on silverstripe.org -* [All issues across modules](https://www.silverstripe.org/community/contributing-to-silverstripe/github-all-core-issues) - -## Identifying issues and pull request relevant to your own project {#identifying-issues} - -Our [issue browser](https://silverstripe-github-issues.now.sh/) can be helpful to identify known issues and pending pull requests in -[supported modules](/project_governance/supported_modules/). -But you're usually only running some of these modules, and others -from the [wider module ecosystem](https://addons.silverstripe.org). - -In order to only show issues and pull requests relevant to your project, -we've written a little [composer utility](https://github.com/silverstripe/silverstripe-github-issue-search-composer-util) -which inspects your own `composer.lock` file dependencies, -and searches across all Silverstripe CMS modules in there. - -After [installing the composer utility](https://github.com/silverstripe/silverstripe-github-issue-search-composer-util), -use this command to pass through a lock file, and get a URL to open in your favourite browser. - -``` -cat /my/project/composer.lock | ss-issue-search get-url -``` - -Protip: You can further filter to certain [issue labels](code#labels) -such as `label:impact/high` to make the results more relevant. +Silverstripe CMS does not operate a _bug bounty_ program. + +## GitHub Labels {#labels} + +The current GitHub labels are grouped into five sections: + +1. *Impact* - What impact does this issue have, does it break a feature completely, is it just a side effect or is it trivial and not a big problem (but a bit annoying), etc. Impact is evaluated in the context of the CMS as a whole, rather than against the individual module the issue is raised on. +2. *Complexity* - What level of technical proficiency is required to address this issue? +3. *Type* - The type of solution required to address this issue +4. *Affects* - The release line this issue is relevant to +5. *RFC* - The issue is a request-for-comment + +| Label | Purpose | +| ----- | ------- | +| impact/critical | Website breaking issue with no workarounds. Reserved only for bugs. Bugfix's will target all supported minor release lines. | +| impact/high | Affects a major usage flow. Broken functionality with no obvious workarounds available, or an enhancement that provides a clear benefit to users | +| impact/medium | When affecting a major usage flow, for bugs there is a workaround available and for enhancements there would be a reasonable benefit to users. For a less common usage flow there is broken functionality and for enhancements there is a clear benefit to users. | +| impact/low | A nuisance but doesn't break any functionality (typos, etc). For enhancements there would only be a limited benefit to users. | +| complexity/low | Someone with limited Silverstripe CMS experience could resolve | +| complexity/medium | Someone with a good understanding of Silverstripe CMS could resolve | +| complexity/high | Only an expert with Silverstripe CMS could resolve | +| type/bug | Does not function as intended, or is inadequate for the purpose it was created for | +| type/enhancement | New feature or improvement for either users or developers | +| type/api-break | An API-breaking change requiring a new major release | +| type/ux | Impact on the CMS user interface | +| type/docs | A docs change | +| type/userhelp | A userhelp documentation change | +| affects/* | Issue has been observed on a specific CMS release line | +| rfc/draft | [RFC](/project_governance/request_for_comment) under discussion | +| rfc/accepted | [RFC](/project_governance/request_for_comment) where agreement has been reached | diff --git a/en/05_Contributing/01_Code.md b/en/05_Contributing/01_Code.md index 9df6eb32e..09518073c 100644 --- a/en/05_Contributing/01_Code.md +++ b/en/05_Contributing/01_Code.md @@ -6,255 +6,259 @@ icon: code # Contributing Code - Submitting Bugfixes and Enhancements -Silverstripe CMS will never be finished, and we need your help to keep making it better. If you're a developer a great way to get involved is to contribute patches to our modules and core codebase, fixing bugs or adding features. +[info] +If you want to contribute changes to documentation, please read through the [contributing documentation](./documentation) page. +[/info] -The Silverstripe CMS core modules (`framework` and `cms`), as well as some of the more popular modules are in -git version control. Silverstripe CMS hosts its modules on [github.com/silverstripe](https://github.com/silverstripe/). After [installing git](https://help.github.com/articles/set-up-git/) and creating a [free github.com account](https://github.com/join/), you can "fork" a module, -which creates a copy that you can commit to (see github's [guide to "forking"](https://help.github.com/articles/fork-a-repo/)). +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). -For other modules, our [add-ons site](https://addons.silverstripe.org/add-ons/) lists the repository locations, typically using the version control system like "git". - -If you are modifying CSS or JavaScript files in core modules, you'll need to regenerate some files. -Please check out our [client-side build tooling](build_tooling) guide for details. +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). [hint] -Note: By supplying code to the Silverstripe CMS core team in patches, tickets and pull requests, you agree to assign copyright of that code to Silverstripe Limited, on the condition that Silverstripe Limited releases that code under the BSD license. +Note: By supplying code to the Silverstripe CMS core team in issues and pull requests, you agree to assign copyright of that code to Silverstripe Limited, on the condition that Silverstripe Limited releases that code under the BSD license. -We ask for this so that the ownership in the license is clear and unambiguous, and so that community involvement doesn't stop us from being able to continue supporting these projects. By releasing this code under a permissive license, this copyright assignment won't prevent you from using the code in any way you see fit. +We ask for this so that the ownership in the license is clear and unambiguous, and so that community involvement doesn't stop us from being able to continue supporting these projects. By releasing this code under a permissive license, this copyright assignment won't prevent you from using the code in any way you see fit. [/hint] -## Step-by-step: From forking to sending the pull request +## Before you start working {#before-you-start} -[notice] -**Note:** Please adjust the commands below to the version of Silverstripe CMS that you're targeting. -[/notice] +There are a few things that you should do before you start working on a fix: -1. Create a [fork](https://help.github.com/articles/about-forks/) of the module you want to contribute to (listed on [github.com/silverstripe/](https://github.com/silverstripe/)). +### Consider if your change should be its own module -1. Install the project through composer. The process is described in detail in "[Installation through Composer](../getting_started/composer#contributing)". +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). - ```bash - composer create-project --keep-vcs silverstripe/installer ./your-website-folder 5.0.x-dev - ``` +### Check for an existing pull request -1. Add a new "upstream" remote to the module you want to contribute to (e.g. `cms`). -This allows you to track the original repository for changes, and rebase/merge your fork as required. -Use your Github user name for which you created the fork in Step 1. +Check to see if someone else has already submitted a pull request for this change by searching on GitHub. If they have, consider collaborating with them by reviewing their PR. - ```bash - cd framework - git remote rename origin upstream - git branch --set-upstream-to upstream - git remote add -f origin git://github.com//silverstripe-framework.git - ``` +### Make or find a GitHub issue -1. [Branch for new issue and develop on issue branch](code#branch-for-new-issue-and-develop-on-issue-branch) +Whether you're fixing a bug, updating documentation, making an ehancement for an existing feature, or even a brand new feature, you must link your pull request to a GitHub issue. - ```bash - # verify current branch 'base' then branch and switch - cd framework - git status - git checkout -b - ``` +If there's an existing GitHub issue, there may already be some discussion there about the preferred approach. Make sure you read through the comments. -1. As time passes, the upstream repository accumulates new commits. Keep your working copy's branch and issue branch up to date by periodically running a `composer update`. -As a first step, make sure you have committed all your work, then temporarily switch over to the `master` branch while updating. -Alternatively, you can use [composer "repositories"](https://getcomposer.org/doc/05-repositories.md#vcs), -but we've found that dramatically slows down any updates. You may need to [resolve conflicts](https://help.github.com/articles/resolving-merge-conflicts-after-a-git-rebase/). +If there _isn't_ an existing issue, you should create one. Make sure you mention in your issue that you intend to make a pull request to implement the change (especially if this is for a new feature). - ```bash - cd framework && git checkout master - composer update - cd framework && git checkout - cd framework && git rebase upstream/master - ``` +If you are planning to develop an extensive feature or fix a bug that could have wide-reaching effects, try to get some discussion in your issue before you do much coding. Make it clear in the issue that you want to discuss it before working on it, and consider discussing the problem in one of the [community channels](https://www.silverstripe.org/community/) (and summarise the discussion in the issue afterward). -1. When development is complete, run another update, and consider [squashing your commits](https://help.github.com/articles/using-git-rebase-on-the-command-line/) +Refer to [Contributing Issues](./issues_and_bugs/) for more information about finding and creating GitHub issues. -1. Push your branch to your GitHub fork +## Step-by-step: how to contribute code {#step-by-step} - ```bash - cd framework - git push origin - ``` +[notice] +The examples below assume you are making a change that applies to the `5.1` branch. -1. Issue pull request on GitHub. Visit your forked repository on gitHub.com and click the "Create Pull Request" button next to the new branch. +Please adjust the commands as appropriate for the version of Silverstripe CMS that you're targeting. See [picking the right version](#picking-the-right-version). +[/notice] -Please read [collaborating with pull requests](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/) on github.com -for more details. +### Editing files directly on GitHub.com -The core team is then responsible for reviewing patches and deciding if they will make it into core. If -there are any problems they will follow up with you, so please ensure they have a way to contact you! +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. -### Picking the right version +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. -The Silverstripe CMS project follows the [Semantic Versioning](https://semver.org) (SemVer) specification for releases. -It clarifies what to expect from different releases, and also guides you in choosing the right branch to base your pull request on. +Make sure you read the [picking the right version](#picking-the-right-version), [create the pull request](#create-the-pr), and [recieve and respond to feedback](#recieve-feedback) sections below. -If you are unsure what branch your pull request should go to, consider asking in the GitHub issue that you address with your patch, or -simply choose the "default branch" of the repository where you want to contribute to. That would usually target the next minor release of the module. +### Step 1: Picking the right version {#picking-the-right-version} -If you are changing existing APIs, introducing new APIs or major new features, -please review our guidance on [supported versions](release_process#supported-versions). -You will need to choose the branch for your pull request accordingly. +The Silverstripe CMS project follows [Semantic Versioning](https://semver.org), which clarifies what to expect from different releases and also guides you in choosing the right branch to base your pull request on. -As we follow SemVer, we name the branches in repositories accordingly -(using BNF rules defined by [semver.org](https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions)): - - `` branches contain major versions and all changes for yet unreleased minor versions - - ` "." ` branches contain released minor versions and all changes for yet to be released patch versions +As we follow semantic versioning, we name the branches in repositories accordingly: +- `` (e.g. `5`) branches contain all changes for upcoming major or minor releases. These are called "major release branches" or "minor release branches", depending on whether they represent the next major release or the next minor release. +- `.` (e.g. `5.1`) branches contain all changes for upcoming patch releases. These are called "patch release branches". -Silverstripe CMS public APIs explicitly include: - - namespaces, classes, interfaces and traits - - public and protected scope (including methods, properties and constants) - - global functions, variables - - yml configuration file structure and value types - - private static class properties (considered to be configuration variables) +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/). -Silverstripe CMS public APIs explicitly exclude: - - private scope (methods and properties with the exception for `private static`) - - entities marked as `@internal` - - yml configuration file default values - - HTML, CSS, JavaScript, TypeScript, SQL and anything else that is not PHP +#### For changes to public API or new/enhanced features -Other entities might be considered to be included or excluded from the public APIs on case-by-case basis. +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. -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 bug. +#### For bug fixes that don't introduce new API -API from third party dependencies may indirectly be incorporated into Silverstripe CMS's 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. +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. -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. +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. -### The Pull Request Process +#### For API breaking changes -Once your pull request is issued, it's not the end of the road. A [core committer](/project_governance/core_committers/) will most likely have some questions for you and may ask you to make some changes depending on discussions you have. -If you've been naughty and not adhered to the [coding conventions](coding_conventions), -expect a few requests to make changes so your code is in-line. +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. +e.g. if the latest stable release is `5.2.7`, the major release branch would be `6`. -If your change is particularly significant, it may be referred to the [forum](https://forum.silverstripe.org) for further community discussion. +#### Definition of public API -A core committer will also "label" your PR using the labels defined in GitHub, these are to correctly classify and help find your work at a later date. +Silverstripe CMS public APIs explicitly include (unless excluded below): -#### GitHub Labels {#labels} +- **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'));`) -The current GitHub labels are grouped into five sections: +Silverstripe CMS public APIs explicitly exclude: -1. *Impact* - What impact does this bug/issue/fix have, does it break a feature completely, is it just a side effect or is it trivial and not a bit problem (but a bit annoying). Impact is evaluated in the context of the CMS as a whole, rather than against the individual module the issue is raised on. -2. *Complexity* - What level of technical proficiency is required to address this issue? -3. *Type* - The type of solution required to address this issue -4. *Affects* - The release line this issue is relevant to -5. *RFC* - The issue is a request-for-comment +- 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 -| Label | Purpose | -| ----- | ------- | -| impact/critical | Website breaking issue with no workarounds. Reserved only for bugs. Bugfix's will target all supported minor release lines. | -| impact/high | Affects a major usage flow. Broken functionality with no obvious workarounds available, or an enhancement that provides a clear benefit to users | -| impact/medium | When affecting a major usage flow, for bugs there is a workaround available and for enhancements there would be a reasonable benefit to users. For a less common usage flow there is broken functionality and for enhancements there is a clear benefit to users. | -| impact/low | A nuisance but doesn't break any functionality (typos, etc). For enhancements there would only be a limited benefit to users. | -| complexity/low | Someone with limited Silverstripe CMS experience could resolve | -| complexity/medium | Someone with a good understanding of Silverstripe CMS could resolve | -| complexity/high | Only an expert with Silverstripe CMS could resolve | -| type/bug | Does not function as intended, or is inadequate for the purpose it was created for | -| type/enhancement | New feature or improvement for either users or developers | -| type/api-break | An API-breaking change requiring a new major release | -| type/ux | Impact on the CMS user interface | -| type/docs | A docs change | -| type/userhelp | A userhelp documentation change | -| affects/* | Issue has been observed on a specific CMS release line | -| rfc/draft | [RFC](/project_governance/request_for_comment) under discussion | -| rfc/accepted | [RFC](/project_governance/request_for_comment) where agreement has been reached | +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. -### Quickfire Do's and Don't's +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. -If you aren't familiar with git and GitHub, try reading the ["GitHub bootcamp documentation"](https://help.github.com/). -We also found the [free online git book](https://git-scm.com/book/en/v2) and the [git crash course](https://services.github.com/) useful. -If you're familiar with it, here's the short version of what you need to know. Once you fork and download the code: +API from third party dependencies may implicitly be incorporated into our definition of public API if: -* **Don't develop on the master branch.** Always create a development branch specific to "the issue" you're working on (on our [GitHub repository's issues](https://github.com/silverstripe/silverstripe-framework/issues)). Name it by issue number and description. For example, if you're working on Issue #100, a `DataObject::get_one()` bugfix, your development branch should be called 100-dataobject-get-one. If you decide to work on another issue mid-stream, create a new branch for that issue--don't work on both in one branch. +- 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. -* **Do not merge the upstream master** with your development branch; *rebase* your branch on top of the upstream master. +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. -* **A single development branch should represent changes related to a single issue.** If you decide to work on another issue, create another branch. +### Step 2: Install the project {#install-the-project} -* **Squash your commits, so that each commit addresses a single issue.** After you rebase your work on top of the upstream master, you can squash multiple commits into one. Say, for instance, you've got three commits in related to Issue #100. Squash all three into one with the message "Description of the issue here (fixes #100)" We won't accept pull requests for multiple commits related to a single issue; it's up to you to squash and clean your commit tree. (Remember, if you squash commits you've already pushed to GitHub, you won't be able to push that same branch again. Create a new local branch, squash, and push the new squashed branch.) +Install the project through composer. The process is described in detail in the [getting started](../getting_started/composer#contributing) docs. -* **Choose the correct branch**: see [Picking the right version](#picking-the-right-version). +```bash +composer create-project --keep-vcs silverstripe/installer ./your-website-folder 5.1.x-dev +``` -### Editing files directly on GitHub.com +Note that if you already have a working project and would like to implement the change in the context of that project, you will need to make sure you have the full source of the module using the [`composer reinstall`](https://getcomposer.org/doc/03-cli.md#reinstall) command: + +```bash +# re-install the module using prefer-source. +# replace / with the module you're making changes to (e.g. silverstripe/framework) +composer reinstall / --prefer-source +``` + +### Step 3: Prepare your working directory {#prepare-your-working-directory} + +- Create a [fork](https://help.github.com/articles/about-forks/) of the module you want to contribute to by going to the repository in your browser, clicking the "fork" button, and following the instructions. + +- Add your fork as a "remote" to the module you want to contribute to. This is where you will be pushing changes to. + + ```bash + cd vendor// + git remote add pr git@github.com:/.git + ``` + +- Create a working branch. -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 has an "edit this file" link. + ```bash + # make sure you're starting from the correct branch first + cd vendor// + git checkout --track origin/5.1 + # then create your working branch + git checkout -b + ``` + +[hint] +Use a descriptive name for your branch. For example if you are fixing a bug related to swapping preview modes targetting the `5.1` branch: `pulls/5.1/fix-preview-modes` +[/hint] -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. +### Step 4: Work on your pull request {#work-on-your-pr} -## Check List +Work on the code as much as you want and commit as often as you need to, but keep the following in mind: -* Adhere to our [coding conventions](/contributing/coding_conventions) -* If your patch is extensive, discuss it first on the [Silverstripe CMS Forums](https://forum.silverstripe.org/c/feature-ideas) (ideally before doing any serious coding) -* When working on existing tickets, provide status updates through ticket comments -* Check your patches against the "master" branch, as well as the latest release branch -* Write [unit tests](../developer_guides/testing/unit_testing) -* Write [Behat integration tests](https://github.com/silverstripe/silverstripe-behat-extension) for any interface changes -* Describe specifics on how to test the effects of the patch -* It's better to submit multiple patches with separate bits of functionality than a big patch containing lots of changes -* Only submit a pull request for work you expect to be ready to merge. Work in progress is best discussed in an issue, or on your own repository fork. -* Document your code inline through [PHPDoc](https://en.wikipedia.org/wiki/PHPDoc) syntax. See our -[API documentation](https://api.silverstripe.org/) for good examples. -* Check and update documentation on [docs.silverstripe.org](https://docs.silverstripe.org). Check for any references to functionality deprecated or extended through your patch. Documentation changes should be included in the patch. -* When introducing something "noteworthy" (new feature, API change), [update the release changelog](/changelogs) for the next release this commit will be included in. -* If you get stuck, please post to the [forum](https://www.silverstripe.org/community/forums) -* When working with the CMS, please read the ["CMS Architecture Guide"](/developer_guides/customising_the_admin_interface/cms_architecture) first -* Try to respond to feedback in a timely manner. PRs that go more than a month without a response from the author are considered stale, and will be politely chased up. If a response still isn't received, the PR will be closed two weeks after that. +- Adhere to our [coding conventions](/contributing/coding_conventions) +- Most pull requests only need a single commit, but complex changes might be better served with multiple commits. In either case, each commit must have a clear and distinct purpose +- Commit messages should conform to our [commit message guidelines](#commit-messages) +- Document new API through [PHPDoc](https://en.wikipedia.org/wiki/PHPDoc) comments. These are used in IDEs and in our [API documentation](https://api.silverstripe.org/). +- Add [unit tests](../developer_guides/testing/unit_testing) which prove your change works and which will prevent future regressions +- Add [behat tests](https://github.com/silverstripe/silverstripe-behat-extension) for any complex behaviour and for any JavaScript functionality changes +- Avoid making unrelated changes (such as fixing coding standards) which are not the focus of your pull request. Those sorts of changes increase the work required to review your pull request. +- It's better to submit multiple pull requests with separate bits of functionality than a big pull request containing lots of changes. If your pull request contains lots of unrelated changes you will be asked to submit them as separate pull requests. +- If you are adding a new feature or changing the way an existing feature behaves, you will need to also create a pull request against [silverstripe/developer-docs](https://github.com/silverstripe/developer-docs) to update the documentation and add information about the change to the changelog. +- If you have updated any source files for CSS or JavaScript, you'll need to build and commit the dist files. See [client-side build tooling](build_tooling) for details. -## Commit Messages +#### Commit messages -We try to maintain a consistent record of descriptive commit messages. +We try to maintain a consistent record of descriptive commit messages. Most importantly: Keep the first line short, and add more detail below. -This ensures commits are easy to browse, and look nice on github.com -(more info about [proper git commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)). +This ensures commits are easy to browse and quickly see what the purpose of the commit is. -Our [changelog](https://docs.silverstripe.org/en/changelogs/) generation tool relies upon commit prefixes (tags) -to categorize the patches accordingly and produce more readable output. Prefixes are usually a single case-insensitive word, -at the beginning of the commit message. Although prefixing is optional, **noteworthy** patches should have them to fall into -correct categories. +Our [changelog](https://docs.silverstripe.org/en/changelogs/) generation tool relies upon commit prefixes +to categorize commits and produce more readable output. The prefixes are a single case-insensitive term +at the beginning of the commit message. | Prefix | Description | | --- | --- | -| API | Addition of a new API, or modification/removal/deprecation of an existing API. Includes any change developers should be aware of when upgrading. | -| FIX | Bugfix on something developers or users are likely to encounter. | -| DOC | Any documentation changes. | +| API | Addition of a new public/protected API, or modification/removal/deprecation of an existing API. | | NEW | New feature or major enhancement (both for users and developers) | | ENH | Improvements of existing functionality (with no API changes), UI/UX enhancements, refactoring and configuration updates. | -| MNT | Maintenance commits that have no impact on users and applications (e.g. CI configs) | +| FIX | Bugfix on something developers or users are likely to encounter. | +| DOC | Any documentation changes. | | DEP | Dependency version updates (updates for composer.json, package.json etc) | -| Merge | PR merges and merge-ups | - -If you can't find the correct prefix for your commit, it is alright to leave it untagged, then it will fall into "Other" category. +| MNT | Maintenance commits that have no impact on users and applications (e.g. CI configs) - ommitted from the changelog | +| Merge | PR merges and merge-ups - ommitted from the changelog | -Further guidelines: +If you can't find the correct prefix for your commit, it is alright to leave it untagged. The commit will then fall into "Other" category. -* Each commit should form a logical unit - if you fix two unrelated bugs, commit each one separately -* If you are fixing a issue from our bugtracker (see [Reporting Bugs](issues_and_bugs)), please append `(fixes #)` -* When fixing issues across repos (e.g. a commit to `framework` fixes an issue raised in the `cms` bugtracker), - use `(fixes silverstripe/silverstripe-cms#)` ([details](https://github.com/blog/1439-closing-issues-across-repositories)) -* If your change is related to another commit, reference it with its abbreviated commit hash. -* Mention important changed classes and methods in the commit summary. +Example: Good commit message -Example: Bad commit message +```text +FIX Allow multiple iterations of eager-loaded DataLists -``` -finally fixed this dumb rendering bug that Joe talked about ... LOL -also added another form field for password validation +Previously, a second iteration would add every relation item to the +relation list a second time - so with each iteration your relation list +count doubled (though it was the same records time and again). ``` -Example: Good commit message +### Step 5: Create the pull request {#create-the-pr} + +When you are ready, push your branch to your GitHub fork. It's also a good idea to do this during development if the process is taking more than one day since this effectively backs up your work for you. +Only submit a pull request for work you think is ready to merge. Work in progress is best discussed in an issue (you can link to the code in your fork if you need to refer to it). + +```bash +cd vendor// +git push pr ``` -FIX Formatting through prepValueForDB() -Added prepValueForDB() which is called on DBField->writeToManipulation() -to ensure formatting of value before insertion to DB on a per-DBField type basis (fixes #1234). -Added documentation for DBField->writeToManipulation() (related to a4bd42fd). +Then [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) on GitHub. If you are raising multiple pull requests that work together to solve a problem, make sure you link to them and indicate what the dependencies are (e.g. one PR might require another in order to work and for the tests to pass - in that case we need to know which to merge first). + +If there is a template for the pull request description, follow it as closely as you can. If there isn't, then provide a quick summary of what your changes are, why you're making them, and a link to the relevant GitHub issue. Make sure to include steps to manually test the effects of the change. + +It's also a good idea to add a link to your PR in the relevant GitHub issue. Add the link in the issue description if you have edit rights, and in a new comment otherwise. Doing this improves the chances of your PR being noticed. + +Following these additional guidelines for your pull request will improve the chances that your change will be merged: + +- Link to [the relevant GitHub issue](#make-or-find-a-github-issue) from your pull request description +- Link to your pull request from that issue (in the description if you can edit it, or in a comment otherwise) +- Explain your implementation. If there's anything which you needed to do a deep dive to find the best way to do it, or anything potentially controversial, etc, you can add a comment to your own pull request explaining what you did and why you did it that way. + +### Step 6: Recieve and respond to feedback {#recieve-feedback} + +Once your pull request is created, it's not the end of the road. + +#### Automated feedback + +Most of the core and supported repositories have an automated GitHub Actions workflow which will run on your pull request. When it finishes running, check for any failed builds. + +If you think a build has failed for reasons unrelated to the changes you've made, point that out in a comment. If the failure _is_ related to your changes, then make any adjustments necessary to resolve the problems. + +#### Peer review feedback + +The core team will review the pull request as time permits. They will most likely have some questions for you and may ask you to make some changes, so make sure you have [configured your GitHub notifications](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications) appropriately. + +- Try to respond to feedback in a timely manner. PRs that go for a while without a response from the author are considered stale, and will be politely chased up. If a response still isn't received, the PR will eventually be closed. +- If you don't agree with a requested change, provide a clear reason why. Bonus points for showing precedent in the existing codebase. But be open to accepting alternative view points - if a member of the core team insists that you make the change after responding to your reasoning, it's often best to defer to their judgment. + +#### Resolving merge conflicts + +If other changes are merged in before yours, your pull request may end up with merge conflicts. You'll need to resolve those by rebasing your branch on top of the target branch, and then manually resolving the merge conflicts. + +[warning] +Using `--force-with-lease` is necessary after a rebase, because otherwise GitHub will reject your push. This is because your commit hashes will have changed. But beware that you are explicitly telling GitHub that you are intentionally overriding data. Make sure you have the correct branch name when doing that step to avoid accidentally overriding other branches in your forked repository. +[/warning] + +```bash +cd vendor// +git checkout 5.1 +git pull +git checkout +git rebase 5.1 +# if there are merge conflicts, resolve them at this stage then run git rebase --continue +git push pr --force-with-lease ``` diff --git a/en/05_Contributing/02_Build_Tooling.md b/en/05_Contributing/02_Build_Tooling.md index d47018c8d..e19939970 100644 --- a/en/05_Contributing/02_Build_Tooling.md +++ b/en/05_Contributing/02_Build_Tooling.md @@ -1,98 +1,91 @@ --- title: Build tooling -summary: The tools we use to compile our frontend code +summary: The tools we use to compile our client-side code icon: tools --- # Client-side build tooling -Core JavaScript, CSS, and thirdparty dependencies are managed with the build tooling +Core JavaScript, CSS, and thirdparty client-side dependencies are managed with the build tooling described below. -Note this only applies to core SilverStripe dependencies, you're free to manage +Note this only applies to core Silverstripe CMS dependencies, you're free to manage dependencies in your project codebase however you like. ## Installation -The [NodeJS](https://nodejs.org) JavaScript runtime is the foundation of our client-side +The [Node.js](https://nodejs.org) JavaScript runtime is the foundation of our client-side build tool chain. If you want to do things like upgrade dependencies, make changes to core JavaScript or SCSS files, you'll need Node installed on your dev environment. -Our build tooling supports the v18.x ([LTS as of October 2022](https://github.com/nodejs/release#release-schedule)) version -of NodeJS. +We recommend using the +[Node Version Manager](https://github.com/creationix/nvm) (nvm) to ensure you use the appropriate +version of node. -If you already have a different version of NodeJS installed, check out the -[Node Version Manager](https://github.com/creationix/nvm) to run multiple versions -in your environment. We aim to have a `.nvmrc` file in each repository, so you just need -to run `nvm use` to swap to the correct node version. +If you're using nvm, make sure you use it to install and swap to the correct version of node +before you run any of the yarn commands. -[yarn](https://yarnpkg.com/) is the package manager we use for JavaScript and SCSS dependencies. -The configuration for an npm package goes in `package.json`. +```bash +nvm install && nvm use +``` + +[yarn](https://yarnpkg.com/) is the package manager we use for JavaScript dependencies. You'll need to install yarn after Node.js is installed. See [yarn installation docs](https://yarnpkg.com/en/docs/install). We recommend using `npm` which comes with Node.js to install it globally. -```sh +```bash npm install -g yarn ``` Once you've installed Node.js and yarn, run the following command once in the `silverstripe/admin` module folder and in each module folder you are working on: -```sh +```bash yarn install ``` -## The Basics: ES6, Webpack and Babel - -[Webpack](https://webpack.github.io) contains the build tooling to -"transpile" various syntax patterns into a format the browser can understand, -and resolve ECMA `import` statements ([details](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)). -Webpack provides the entry point to our build tooling through a `webpack.config.js` -file in the root folder of each core module. +[notice] +The `silverstripe/admin` repository includes some components and dependencies that other modules +need to work. Make sure that in addition to the module(s) who's code you're touching, you also run +`yarn install` in the directory for `silverstripe/admin`. -[Babel](https://babeljs.io/) is a JavaScript compiler. It takes JavaScript files as input, -performs some transformations, and outputs other JavaScript files. This allows us to use modern syntax -in source files, while ensuring the output is converted to syntax that is supported by the browser. -In SilverStripe we use Babel to transform our JavaScript in two ways. +You may need to first run `composer reinstall silverstripe/admin --prefer-source` if you installed +that module without `--prefer-source` originally. +[/notice] ## Build Commands The `script` property of a `package.json` file can be used to define command line [scripts](https://docs.npmjs.com/misc/scripts). -A nice thing about running commands from an npm script is binaries located in -`node_modules/.bin/` are temporally added to your `$PATH`. This means we can use dependencies -defined in `package.json` for things like compiling JavaScript and SCSS, and not require -developers to install these tools globally. This means builds are much more consistent -across development environments. -To run an npm script, open up your terminal, change to the directory where `package.json` +To run one of these scripts, open up your terminal, change to the directory where `package.json` is located, and run `yarn `. Where `` is the name of the script you wish to run. ### build -```sh +During development, you'll want to build the core JavaScript and CSS files in development mode. +This is faster than `yarn build` below and outputs the files in a format that is useful for debugging. + +```bash yarn dev ``` -Runs [Webpack](https://webpack.github.io/) to builds the core JavaScript and CSS files in development mode. -This is faster than `yarn build` below and outputs the files in a format that is useful for debugging. +You might want to automatically rebuild whenever you change a `.js` or `.scss` file. +This is useful for when you are rapidly making lots of small changes. -```sh +```bash yarn watch ``` -The same as `yarn dev`, except it will automatically rebuild whenever you change a `.js` or `.scss` file. -This is useful for when you are rapidly making lots of small changes. +When you've finished making your changes, build the core JavaScript and CSS files in production mode. +You will need to run this script before committing your changes to git. -```sh +```bash yarn build ``` -Runs [Webpack](https://webpack.github.io/) to builds the core JavaScript and CSS files in production mode. -You will need to run this script before committing your changes to git. - -### build JavaScript or CSS separately +#### build JavaScript or CSS separately If you are only working on JavaScript or only working on CSS you might want to only build what you're working on. You can do this by adding `WEBPACK_CHILD=css` or `WEBPACK_CHILD=js` before the relevant yarn command, for example: @@ -102,38 +95,21 @@ WEBPACK_CHILD=css yarn dev The `css` or `js` portion of this is defined in the `webpack.config.js` file. Some modules may also include other configured components that can be built independently as well. -### lint +### lint and test -```sh -yarn lint -``` - -Run linters (`eslint` and `sass-lint`) to enforce -our [JavaScript](/contributing/javascript_coding_conventions) and -[CSS](/contributing/css_coding_conventions) coding conventions. - -### test +You can lint and run JavaScript unit tests manually - though note that these are also automatically run as part of the `yarn build` script. +You will not be able to build production-ready distribution files if either of these fails. -```sh +```bash +yarn lint yarn test ``` -Runs the JavaScript unit tests. - -### coverage - -```sh -yarn coverage -``` +## Requiring Silverstripe CMS JavaScript modules in your own CMS customisation -Generates a coverage report for the JavaScript unit tests. The report is generated -in the `coverage` directory. - -## Requiring Silverstripe JavaScript modules in your own CMS customisation - -Silverstripe creates bundles which contain many dependencies you might also +Silverstripe CMS creates bundles which contain many dependencies you might also want to use in your own CMS customisation (e.g. `react`). -You might also need some of SilverStripe's own JavaScript ECMA modules (e.g. `components/FormBuilder`). +You might also need some of Silverstripe CMS's own JavaScript components (e.g. `components/FormBuilder`). To avoid transpiling these into your own generated bundles, we have exposed many libraries as [Webpack externals](https://webpack.js.org/configuration/externals/). @@ -170,25 +146,3 @@ import FormBuilder from 'components/FormBuilder/FormBuilder'; ``` For a more in-depth explanation of how to use `@silverstripe/webpack-config` [take a look at the readme](https://www.npmjs.com/package/@silverstripe/webpack-config). - -## Publishing frontend packages to NPM - -We're progressing to include NPM modules in our development process. We currently have a limited number of -[JavaScript only projects published to NPM under the `@silverstripe` organisation](https://www.npmjs.com/search?q=%40silverstripe). - -When a pull request is merged against one of those JS-only projects, a new release has to be published to NPM. Regular -Silverstripe CMS modules using these packages have to upgrade their JS dependencies to get the new release. - -These are the steps involved to publish a new version to NPM for a package, similar steps apply for creating a new -package under the `@silverstripe` organisation: - -1) Make your changes, pull from upstream if applicable -2) Change to the relevant container folder with the `package.json` file -3) Run `npm login` and make sure you’re part of the `@silverstripe` organisation -4) Make sure the `name` property of the `package.json` file matches to the right module name with organisation name prefix, e.g. `"name": "@silverstripe/webpack-config"` -5) Update the `version` property of the `package.json` file with a new version number, following semantic versioning where possible -6) Run `npm version` and validate that the version matches what you expect -7) Run `npm publish` - -_IMPORTANT NOTE_: You cannot publish the same or lower version number. Only members of the Silverstripe CMS core team -can publish a release to NPM. diff --git a/en/05_Contributing/04_Release_Process.md b/en/05_Contributing/04_Release_Process.md index 3db3f7a42..86a2dba0e 100644 --- a/en/05_Contributing/04_Release_Process.md +++ b/en/05_Contributing/04_Release_Process.md @@ -55,11 +55,11 @@ All Silverstripe CMS recipes are released in lock step with each other. For exam contain `silverstripe/recipe-cms` 5.3.1 and `silverstripe/recipe-core` 5.3.1. These recipes may contain various patch versions of its modules within the same minor release line (5.3 in this example). -## Regular quarterly releases +## Regular minor releases -A regular Silverstripe CMS release is tagged on a quarterly basis, in the months: March, June, September, December. This usually involves creating a new minor increment of -each core recipe. Regular quarterly releases are preceded by pre-stable releases to help lay the groundwork for the -stable release. +Regular minor releases are preceded by pre-stable releases to help lay the groundwork for the stable release. + +See our [minor release policy](/project_governance/minor_release_policy/) for details about our release cadence. ### Beta phase diff --git a/en/05_Contributing/06_Documentation.md b/en/05_Contributing/06_Documentation.md index 5d5a060be..65dc3755c 100644 --- a/en/05_Contributing/06_Documentation.md +++ b/en/05_Contributing/06_Documentation.md @@ -1,140 +1,250 @@ --- -title: Documentation -summary: Writing guide for contributing to SilverStripe developer and CMS user help documentation. +title: Contributing Documentation +summary: Guide for contributing to Silverstripe CMS developer and CMS user help documentation. icon: file-alt --- # Contributing documentation -Documentation for a software project is a continuing, collaborative effort. We encourage everybody to contribute in any way they can, from simply fixing spelling mistakes, to writing recipes, reviewing existing documentation and translation to other languages. +Documentation for a software project is a continuous, collaborative effort. We encourage everybody to contribute in any way they can whether it's fixing a typo, updating some outdated documentation, or adding missing documentation. -Modifying documentation requires basic knowledge of [PHPDoc](https://en.wikipedia.org/wiki/PHPDoc) and -[Markdown](https://daringfireball.net/projects/markdown/) as well as a GitHub user account. +Modifying documentation requires basic knowledge of [markdown](https://www.markdownguide.org/). Our documentation also includes some additional syntax which you can read about in the [extended markdown syntax](#extended-markdown-syntax) section below. -[info] -Note that there are two sources of documentation, depending on the intended audience. You can see where each of those lives in the [repositories](#repositories) section below. -[/info] +In order to contribute changes to documentation, you will need to [create a GitHub account](https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account). -## Editing online +## Repositories -The easiest way of editing any documentation is by clicking the "Edit on GitHub" button at the bottom of the -page you want to edit. Alternatively, locate the appropriate .md file in the -[silverstripe/developer-docs](https://github.com/silverstripe/developer-docs/) repository and press the "edit" button. **You will need a free GitHub account to do this**. +Note that there are two sources of documentation, depending on the intended audience. +* End-user help: [silverstripe/silverstripe-userhelp-content](https://github.com/silverstripe/silverstripe-userhelp-content/) +* Developer guides: [silverstripe/developer-docs](https://github.com/silverstripe/developer-docs/) - * After editing the documentation, describe your changes in the "commit summary" and "extended description" fields below then press "Commit Changes". - * After committing you changes, you will see a form to submit a Pull Request: "[pull requests](https://support.github.com/features/pull-requests)". You should be able to adjust the version to which your documentation changes apply before submitting the form. Any changes submitted in a pull request will be sent to the core committers for approval. +If you find a problem related to how the documentation is displayed which can't be fixed in the documentation source files, you can [raise an issue](./issues_and_bugs) or [submit a pull request](./code) to the relevant repository below: -[warning] -You should make your changes in the lowest major branch they apply to. For instance, if you fix a spelling issue that you found in the CMS 5 documentation, submit your fix to the `5` branch in Github and it'll be copied to the most recent major version of the documentation automatically. *Don't submit multiple pull requests for the same change*. -[/warning] +* Website code for user and developer docs: [silverstripe/doc.silverstripe.org](https://github.com/silverstripe/doc.silverstripe.org) +* Website code for automatically generated Developer API documentation: [silverstripe/api.silverstripe.org](https://github.com/silverstripe/api.silverstripe.org) -## Editing on your computer +## Branches and commit messages -If you prefer to edit content on your local machine, you can "[fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo)" the -[silverstripe/developer-docs](https://github.com/silverstripe/developer-docs) repository, make changes locally, and then [send us a pull request](https://github.com/silverstripe/developer-docs/compare) to incorporate your changes. +* All documentation commits must follow the [commit message guidelines](./code#commit-messages), and must be prefixed with the `DOC` prefix. +* If you are fixing incorrect or incomplete information, you should create a PR that targets the most recent patch release branch branch for the relevant major release line (e.g. `5.1`). +* If you are adding documentation for functionality that has not yet been released, you should target the most recent minor release branch branch (e.g. `5`). [warning] -If you submit a new feature or an API change, we strongly recommend and request that you include a PR to update the necessary documentation. This helps prevent our documentation from getting out of date. +You should make your changes in the lowest major branch they apply to. For instance, if you fix a spelling issue that you found in the CMS 4 documentation, submit your fix to the `4.13` branch in Github and it'll be copied to the most recent major version of the documentation automatically. *Don't submit multiple pull requests for the same change*. [/warning] -## Repositories +## Editing online -* End-user help: [silverstripe/silverstripe-userhelp-content](https://github.com/silverstripe/silverstripe-userhelp-content/) -* Developer guides: [silverstripe/developer-docs](https://github.com/silverstripe/developer-docs/) -* Website code for user and developer docs: [silverstripe/doc.silverstripe.org](https://github.com/silverstripe/doc.silverstripe.org) -* Developer API documentation: [silverstripe/api.silverstripe.org](https://github.com/silverstripe/api.silverstripe.org) +If you haven't contributed documentation in the past, you will need to fork the repository. If you're editing online, GitHub will guide you through that process before you can edit the documentation. -## Source control +### Simple changes {#editing-online-simple} -Contributing documentation is the same process as providing any other patch (see [Contributing code](code)). +The easiest way of editing any documentation is by clicking the "Edit on GitHub" button at the bottom of the page you want to edit. This works great if all of the changes you want to make are on a single page. -If you are fixing incorrect or incomplete information for the current major version, you should create a PR that targets the branch for the latest stable release (e.g. `5.1`). +Before you start making your changes, take note of what branch you are editing. You will need this when you create the pull request. -If you are adding documentation for functionality that has not yet been released, you should target the most recent _major_ branch (e.g. `5`) +![note the branch you're editing](../_images/contributing/docs-check-the-branch.png) -## What to write +After editing the documentation, click "Commit changes", then describe your changes in the "commit summary" and "extended description" fields below. -See [what to write (jacobian.org)](https://jacobian.org/writing/great-documentation/what-to-write/) for an excellent introduction to the different types of documentation. Also see [producing OSS: "documentation"](https://producingoss.com/en/getting-started.html#documentation) for good rules of thumb -for documenting open source software. +![follow the guidelines to add a descriptive commit message](../_images/contributing/docs-commit-message.png) -## Structure +Click "Propose changes" when you are ready to commit your changes. This saves them to the forked repository on your profile. -* Keep documentation lines shorter than 120 characters. -* Don't duplicate: Search for existing places to put your documentation. Do you really require a new page, or just a new paragraph of text somewhere? -* Use PHPDoc in source code: Leave low level technical documentation to code comments within PHP, in [PHPDoc](https://en.wikipedia.org/wiki/PHPDoc) format. -* API and developer guides are two forms of source code documentation that complement each other. -* API documentation should provide context, ie, the "bigger picture", by referring to developer guides inside your PHPDoc. -* Make your documentation easy to find: Documentation is useful only when it is interlinked so please make sure your contribution doesn't become an inaccessible island. At the very least, put a link to your index page in the same folder. A link to your page can also appear -as "related content" on other resource (e.g. `/tutorials/site_search` might link to `/developer_guides/forms/introduction`). +You will see a form to submit a pull request. Make sure to target your pull request at the correct branch you took note of earlier. + +![target your pull request at the branch you noted earlier](../_images/contributing/docs-use-correct-branch.png) + +Then click "Create pull request". + +Any changes submitted in a pull request will be sent to the core committers for approval. Make sure the pull request follows the guidelines in [create the pull request](./code#create-the-pr), and then see [recieve and respond to feedback](./code#recieve-feedback) for next steps. + +### Larger changes {#editing-online-advanced} + +For any changes that span more than one page, you can edit the documentation in GitHub's web-based editor. + +To learn more, follow the instructions in [GitHub's documentation](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor). + +Once you've made the pull request, make sure the pull request follows the guidelines in [create the pull request](./code#create-the-pr), and then see [recieve and respond to feedback](./code#recieve-feedback) for next steps. + +## Editing on your computer + +If you prefer to edit content on your local machine, follow the instructions on the [contributing code](code) page, since editing documentation on your computer follows that same process. ## Writing style -* Write in second person plural form: Use "we" instead of "I". It gives the text an instructive and collaborative style. -* It's okay to address the reader: For example "First you'll install a webserver" is good style. +* Write in second person form, addressing the reader. For example "First you'll install a webserver" is good style. +* If referring to maintainers of Silverstripe CMS, either explicitly say "the maintainers", or write in second person plural form (use "we" instead of "I") +* Use gender neutral language throughout the document, unless referencing a specific person. Use them, they, their, instead of he and she, his or her. +* Use simple language and words. Avoid uncommon jargon and overly long words. Remember that not everyone speaks English as their primary language. +* Use UK English, not US English. Silverstripe CMS is proudly a New Zealand open source project we use the UK spelling and forms of English. The most common of these differences are -ize vs -ise, or -or vs our (eg color vs colour). * Write in an active and direct voice. -* Mark up correctly: The use of preformatted text, emphasis and bold make technical writing easier to scan. -* Avoid FAQs: FAQs are not a replacement for coherent, well explained documentation. If you've done a good job +* Avoid saying words like "obviously" or "of course". Things that are obvious to you as the writer may not be so obvious to the person reading the documentation. +* Keep documentation lines shorter than 120 characters. +* Avoid FAQs. FAQs are not a replacement for coherent, well explained documentation. If you've done a good job documenting, there shouldn't be any "frequently asked questions" left. -* "SilverStripe" should always appear without a space with both "S"s capitalised. -* Use simple language and words. Avoid uncommon jargon and overly long words. -* Use UK English and not US English. SilverStripe is proudly a New Zealand open source project we use the UK spelling and forms of English. The most common of these differences are -ize vs -ise, or -or vs our (eg color vs colour). -* We use sentence case for titles so only capitalise the first letter of the first word of a title. The only exceptions to this are when using brand names (e.g. SilverStripe), acronyms (e.g. PHP) and class names (e.g. ModelAdmin). -* Use gender neutral language throughout the document, unless referencing a specific person. Use them, they, their, instead of he and she, his or her. -* URLs: if the end of your sentence is a URL then you don't need to use a full stop. -* Bullet points: Sentence case your bullet points. If a bullet point is a full sentence then end with a full stop. If it is a sentence fragment or a comma separated list, full stops are not required. - -## Highlighted blocks - -There are several built-in block styles for highlighting a paragraph of text. Please use these graphical elements +* We use sentence case for titles. Only capitalise the first letter of the first word of a title. The only exceptions to this are when using brand names (e.g. GitHub), acronyms (e.g. PHP) and class names (e.g. ModelAdmin). +* Use `example.com` as the domain of sample URLs and `example.org` and `example.net` when additional domains are required. All of these domains are [reserved by the IANA](https://tools.ietf.org/html/rfc2606#section-3). +* Use appropriate markdown. The use of code blocks, emphasis, lists, and tables make technical writing easier to scan. +* Never leave spaces at the end of a line. +* Use an empty line to separate paragraphs. +* Sentence case your bullet points. If a bullet point is a full sentence then end with a full stop. If it is a sentence fragment or a comma separated list, full stops are not required. +* All code blocks must have an appropriate syntax highlighting hint. For plain text, use "text". +* Code examples should follow our [coding conventions](./coding_conventions). +* Use `App` when the code requires a vendor name (e.g. as the root for namespaces). +* Do not put a `$` in front of lines of bash code examples. +* When referencing directories, always add a trailing slash to avoid confusions with regular files +* "Silverstripe CMS" is used to refer to the Silverstripe CMS open source project as a whole. +* "Silverstripe" is used to refer to the company, where appropriate. + +## Extended markdown syntax + +Silverstripe CMS documentation has a few special syntax extensions that normal markdown doesn't. These are listed below. + +### Callout blocks + +There are several built-in block styles for calling out a paragraph of text. Please use these graphical elements sparingly. -[hint] -"Tip box": A tip box is great for adding, deepening or accenting information in the main text. They can be used for background knowledge, or to provide links to further information (ie, a "see also" link). -[/hint] +[info] +"Info box": An info box is useful for adding, deepening or accenting information in the main text. They can be used for background knowledge, or to provide links to further information (ie, a "see also" link). +[/info] -Code for a Tip box: +Code for an Info box: -``` -[hint] +```text +[info] ... -[/hint] +[/info] ``` -[notice] -"Notification box": A notification box is good for technical notifications relating to the main text. For example, notifying users about a deprecated feature. -[/notice] +[hint] +"Hint box": A hint box is great for pointing out extra use cases or hints about how to use a feature. +[/hint] -Code for a Notification box: +Code for a Hint box: -``` -[notice] +```text +[hint] ... -[/notice] +[/hint] ``` [warning] -"Warning box": A warning box is useful for highlighting a severe bug or a technical issue requiring a user's attention. For example, suppose a rare edge case sometimes leads to a variable being overwritten incorrectly. A warning box can be used to alert the user to this case so they can write their own code to handle it. +"Warning box": A warning box is useful for pointing out gotchas or technical notifications relating to the main text. For example, notifying users about a deprecated feature. [/warning] Code for a Warning box: -``` +```text [warning] ... [/warning] ``` -See [markdown extra documentation](https://michelf.com/projects/php-markdown/extra/#html) for more restrictions -on placing HTML blocks inside Markdown. +[alert] +"Alert box": An alert box is good for for calling out a severe bug or a technical issue requiring a user's attention. For example, suppose a rare edge case sometimes leads to a variable being overwritten incorrectly. An alert box can be used to alert the user to this case so they can write their own code to handle it. +[/alert] + +Code for an Alert box: + +```text +[alert] +... +[/alert] +``` + +### Links to documentation + +Links to other pages in the documentation uses the URL slug, *not* the file name. + +Relative documentation links are prefixed with `./` for pages in the same directory, or `../` for pages in parent directories. For example `[contributing code](./code)` becomes [contributing code](./code) and `[getting started](../getting_started)` becomes [getting started](../getting_started). + +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 + +API documentation is linked in a special way. Give some examples for classes, methods, properties. + +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: + +``[`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: + +``[`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. + +### Anchor links in headings + +Headings automatically include anchor links, which are generated from the heading text. Sometimes you might want to include a shorter or otherwise more useful anchor link instead. To do that, include the desired anchor in a `{#anchor-here}` section after the heading text. The custom anchor does not render as part of the heading text. + +For example: -## Translating documentation +`## This is a really long heading which has a silly anchor {#my-custom-anchor}` -Documentation is kept alongside the source code, typically in a module subdirectory like `framework/docs/en/`. Each language has its own subfolder, which can duplicate parts of or the entire body of documentation. German documentation would, for example, live in `framework/docs/de/`. The -[docsviewer](https://github.com/silverstripe/silverstripe-docsviewer) module that drives -[docs.silverstripe.org](https://docs.silverstripe.org) automatically resolves these subfolders into a language dropdown. +The above heading would normally have a long and silly anchor, but instead it will use the `#my-custom-anchor` anchor. + +### Linking to child and sibling pages {#link-to-children} + +You can list child/sibling pages using the special `[CHILDREN]` syntax. By default these will render as cards with an icon, a title, and a summary if one is available. + +You can change what is displayed using one of the `Exclude`, `Folder`, or `Only` modifiers. These all take folder and/or file names as arguments. Exclude the `.md` extension when referencing files. Arguments can include a single item, or multiple items using commas to separate them. + +* `[CHILDREN Exclude="How_tos,01_Relations"]`: Exclude specific folders or files from the list. Note that folders don't need to be excluded unless the `includeFolders` modifier is also used. +* `[CHILDREN Only="rc,beta"]`: Only include the listed items. This is the inverse of the `Exclude` modifier. +* `[CHILDREN Folder="How_Tos"]`: List the children of the named folder, instead of the children of the *current* folder. This modifier only accepts a single folder as an argument. + +The above can be combined with any of the `asList`, `includeFolders`, and `reverse` modifiers: + +* `[CHILDREN asList]`: Render the children as a description list instead of as cards. The icon is not used when rendering as a list. +* `[CHILDREN includeFolders]`: Include folders as well as files. +* `[CHILDREN reverse]`: Reverse the order of the list. The list is sorted in case sensitive ascending alphabetical order by default. + +The following would render links for all children as a description list in reverse order, including folders but excluding anything called "How_tos": + +`[CHILDREN Exclude="How_tos" asList includeFolders reverse]` + +#### Example {#link-to-children-example} + +With the following file structure: + +```text +00_Model/ +├─ How_Tos + ├─ Dynamic_Default_Fields.md + ├─ Grouping_DataObject_Sets.md + └─ index.md +├─ 00_Data_Model_and_ORM.md +├─ 01_Relations.md +├─ ... +└─ index.md +``` + +Using the `[CHILDREN]` tag on any file directly in the `00_Model/` directory will list all files *including itself* but excluding the `index.md` file. It will not list `How_Tos/` or any file inside that directory unless `includeFolders` is included (`[CHILDREN includeFolders]`), in which case `How_Tos/` will be listed, and will link to the `index.md` file. No other files inside the `How_Tos/` directory will be listed. + +### Page metadata + +We use gatsby to render the documentation. Gatsby defines a syntax for metadata (which it calls frontmatter) [in its documentation](https://www.gatsbyjs.com/docs/how-to/routing/adding-markdown-pages/). This is used to provide useful information about how to render the page when it's being rendered as a child page as described in [linking to child and sibling pages](#link-to-children) above. + +This metadata is always included at the top of a page, in a block fenced in by `---`, e,g: + +```text +--- +title: My page title +summary: This summary, the title, and the icon will all be used when rendering this page as a child. +icon: file-alt +--- +``` -## Further reading +The available keys for this metadata are: -* [Writing great documentation (jacobian.org)](https://jacobian.org/writing/great-documentation/) -* [How tech writing sucks: Five sins](https://www.slash7.com/articles/2006/11/15/tech-writing-the-five-sins) +* `title`: The title of the page when rendered as a child, and in the navigation. +* `summary`: A short sumary of the page which is used when the page is rendered as a child. +* `icon`: An icon which is used when the page is rendered as a child in card format. Must be one of the icons provided by fontawesome 5, excluding brand icons. +* `iconBrand`: An icon which is used when the page is rendered as a child in card format. Must be one of the brand icons provided by fontawesome 5. +* `hideChildren`: If true, doesn't display children of this page in the navigation. Doesn't affect child lists. diff --git a/en/05_Contributing/07_Translations.md b/en/05_Contributing/07_Translations.md index dbf9974b2..65ab70c1b 100644 --- a/en/05_Contributing/07_Translations.md +++ b/en/05_Contributing/07_Translations.md @@ -6,140 +6,103 @@ icon: globe # Contributing Translations -We are always looking for new translators. Even if a specific language already is translated and has an official -maintainer, we can use helping hands in reviewing and updating translations. Important: It is perfectly fine if you -only have time for a partial translation or quick review work - our system accommodates many people collaborating on the -same language. +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. -The content for UI elements (button labels, field titles) and instruction texts shown in the CMS and elsewhere is -stored in the PHP code for a module (see [i18n](../developer_guides/i18n)). All content can be extracted as a "language file", and -uploaded to an online translation editor interface. SilverStripe 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. +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. -Please register a free translator account to get started, even if you just feel like fixing up a few sentences. +Even if a specific language is already translated, we can use helping hands +in reviewing and updating translations. It is perfectly fine if you only have time for a partial translation or quick +review work - our system accommodates many people collaborating on the same language. + +Please [register a free translator account](https://app.transifex.com/signup/open-source/) to get started, even if you just feel like fixing up a few sentences. ## The online translation tool -We provide a GUI for translations through [transifex.com](https://transifex.com). 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://www.transifex.com/silverstripe/) and start translating online! +We provide a GUI for translations through [transifex.com](https://transifex.com). 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! -For all modules listed there, we regularly import new strings as they get committed to the various code -bases, so you're always translating on the latest and greatest version. +If you need help learning how to edit translations in transifex, check out [transifex's documentation](https://help.transifex.com/). ## FAQ -### What happened to getlocalization.com? - -We migrated from getlocalization.com to transifex in mid 2013. - ### How do I translate a module not listed on Transifex? -Most modules maintained by SilverStripe are on Transifex. For other modules, have a look in the module README if -there's any specific instructions. If there aren't, you'll need to translate the YAML files directly. If the module is -on github, you can create a fork, edit the files, and send back your pull request all directly on the website -([instructions](https://help.github.com/articles/fork-a-repo)). +If a core or supported module is not listed on Transifex, usually that means it has no strings which _can_ be translated. +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}') -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 -https://php.net/sprintf for details. The newer `{my-variable}` format works the same way, but makes its intent clearer, +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 +https://php.net/sprintf for details. The newer `{my-variable}` format works the same way, but makes its intent clearer, and allows reordering of placeholders in your translation. ### Do I need to convert special characters (e.g. HTML-entities)? -Special characters (such as german umlauts) need to be entered in their native form. Please don't use HTML-entities -("ä" instead of "ä"). Silverstripe stores and renders most strings in UTF8 (Unicode) format. +Special characters (such as german umlauts) need to be entered in their native form. Please don't use HTML-entities +(use "ä" instead of "`ä`"). Silverstripe stores and renders most strings in UTF8 (Unicode) format. ### How can I check out my translation in the interface? -Currently translated entities are not directly factored into code (for security reasons and release/review-control), so -you can't see them straight away. +Currently translated entities are not directly factored into code (for security reasons and release/review-control), so +you can't see them straight away. -It is strongly encouraged that you check your translation this way, as its a good way to double check your translation -works in the right context. Please use our [`daily-builds`](https://www.silverstripe.org/daily-builds/) for your local -installation, to ensure you're looking at the most up to date interface. See "Download Translations" above to find out -how to retrieve the latest translation files. +If you really want to check your translation out in context before it has been merged into the codebase, you can follow +the instructions in [i18n](/developer_guides/i18n) to add those translations directly to your Silverstripe CMS project. -### Can I change a translation just for one SilverStripe version? +### Can I change a translation just for one Silverstripe CMS version? -While we version control our translation files like all other source code, the online translation tool doesn't have the -same capabilities. A translated string (as identified by its unique "entity name") is assumed to work well in all -releases. If the interface changes in a non-trivial fashion, the new translations required should have new identifiers +While we version control our translation files like all other source code, the online translation tool doesn't have the +same capabilities. A translated string (as identified by its unique "entity name") is assumed to work well in all +releases. If the interface changes in a non-trivial fashion, the new translations required should have new identifiers as well. -Example: We renamed the "Security" menu title to "Users" in our 3.0 release. As it would confuse users of older versions -unnecessarily, we should use a _new_ entity name for this, and avoid the change propagating to an older SilverStripe -version. - ### How do I change my interface language? -Once you've logged into the CMS, you should see the text "Hi ``" near the top left, you can go to -`https://www.example.com/admin/myprofile/` to edit your profile. You can then set the "interface language" from a -dropdown which automatically includes all found translations (based on the files in the `/lang` folders). +Once you've logged into the CMS, you should see your name near the top left. You can click this to edit +your profile. You can then set the "interface language" from a dropdown. ### I've found a piece of untranslatable text -It is entirely possible that we missed certain strings in preparing Silverstripe for translation-support. If you're -technically minded, please read [i18n](../developer_guides/i18n) on how to make it translatable. Otherwise just post your findings -to the forum. - -### How do I add my own module? +It is entirely possible that we missed certain strings in preparing Silverstripe for translation-support. If you're +technically minded, please read [i18n](/developer_guides/i18n) on how to make it translatable and [submit a pull request](./code). -Once you've built a translation-enabled module, you can run the "textcollector" on your local installation for this -specific module (see [i18n](../developer_guides/i18n)). This should find all calls to `_t()` in php and template files, and generate -a new lang file with the default locale (path: `/lang/en.yml`). Upload this file to the online translation -tool, and wait for your translators to do their magic! +Otherwise please [raise a bug report](./issues_and_bugs) so that we can fix it. ### What about right-to-left (RTL) languages (e.g. Arabic)? -SilverStripe doesn't have built-in support for attribute-based RTL-modifications (``). +Silverstripe CMS doesn't have built-in support for attribute-based RTL-modifications (e.g. ``). -We are currently investigating the available options, and are eager to get feedback on your experiences with -translating silverstripe RTL. +If this is something you'd like to implement, we'd be eager to review a [pull request](./code) for it. ### Can I translate/edit the language files in my favorite text editor (on my local installation) -Not for modules managed by transifex.com, including "framework" and "cms. It causes us a lot of work in merging these -files back. Please use the online translation tool for all new and existing translations. +No, because it causes us a lot of work in merging these files back. Please use the online translation tool for all new and existing translations. -### How does my translation get into a SilverStripe release? +### How does my translation get into a Silverstripe CMS release? -Currently this is a manual process of a core team member downloading approved translations and committing them into our +Currently this is a manual process of a core team member downloading approved translations and committing them into our source tree. ### How does my translation get approved, who is the maintainer? -The online translation tool (transifex.com) is designed to be decentralized and collaborative, so there's no strict -approval or review process. Every logged-in user on the system can flag translations, and discuss them with other +The online translation tool (transifex.com) is designed to be decentralized and collaborative, so there's no strict +approval or review process. Every logged-in user on the system can flag translations, and discuss them with other translators. ### I'm seeing lots of duplicated translations, what should I do? -For now, please translate all duplications - sometimes they might be intentional, but mostly the developer just didn't -know their phrase was already translated. Please contact us about any duplicates that might be worth merging. - -### What happened to translate.silverstripe.org? - -This was a custom-built online translation tool serving us well for a couple of years, but started to show its age -(performance and maintainability). It was replaced with transifex.com. All translations from translate.silverstripe.org -were migrated. Unfortunately, the ownership of individual translations couldn't be migrated. - -As the new tool doesn't support the PHP format used in SilverStripe 2.x, this means that we no longer have a working -translation tool for PHP files. Please edit the PHP files directly and [send us pull requests](/contributing). - -This also applies for any modules staying compatible with SilverStripe 2.x. +For now, please translate all duplications - sometimes they might be intentional, but mostly the developer just didn't +know their phrase was already translated. ## Contact -Get in touch with translators on our [community Slack](https://silverstripe.org/slack) - please join the `#translations` -channel. For generic translation and Transifex questions you might like to use -[Stack Overflow](https://stackoverflow.com/search?q=transifex). Alternatively you can start a discussion on +Get in touch with translators on our [community Slack](https://silverstripe.org/slack) - please join the `#translations` +channel. For generic translation and Transifex questions you might like to use +[Stack Overflow](https://stackoverflow.com/search?q=transifex). Alternatively you can start a discussion on [our forum](https://forum.silverstripe.org). - -## Related - - * [i18n](/developer_guides/i18n): Developer-level documentation of Silverstripe's i18n capabilities - * [Translation Process](translation_process): Information about managing translations for the core team and/or module maintainers. - * [tractorcow/silverstripe-fluent](https://github.com/tractorcow/silverstripe-fluent): Simple Silverstripe CMS localisation diff --git a/en/05_Contributing/08_Translation_Process.md b/en/05_Contributing/08_Translation_Process.md deleted file mode 100644 index c430f7b25..000000000 --- a/en/05_Contributing/08_Translation_Process.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Implement Internationalisation -summary: Implement SilverStripe's internationalisation system in your own modules. -icon: globe ---- - -# Implementing Internationalisation - -To find out about how to assist with translating SilverStripe from a user's point of view, see the -[Contributing Translations page](/contributing/translations). - -## Set up your own module for localisation - -### Collecting translatable text - -As a first step, you can automatically collect all translatable text in your module through the `i18nTextCollector` -task. See [i18n](../developer_guides/i18n#collecting-text) for more details. - -### Import master files - -If you don't have an account on transifex.com yet, [create a free account now](https://www.transifex.com/signup/). After -creating a new project, you have to upload the `en.yml` master file as a new "Resource". While you can do this through -the web interface, there's a convenient -[commandline client](https://docs.transifex.com/client/introduction) for this -purpose. In order to use it, set up a new `.tx/config` file in your module folder: - -```yaml -[main] -host = https://www.transifex.com - - -[my-project.master] -file_filter = lang/.yml -source_file = lang/en.yml -source_lang = en -type = YML -``` - -If you don't have existing translations to import, your project is ready to go - simply point translators to the URL, have them -sign up, and they can create languages and translations as required. - -### Import existing translations - -In case you have existing translations in YML format, there's a "New language" option in the web interface. -Alternatively, use the [commandline client](https://docs.transifex.com/client/introduction). - -### Export existing translations - -You can download new translations in YML format through the web interface, but that can get quite tedious for more than -a handful of translations. Again, the [commandline client](https://docs.transifex.com/client/introduction) -provides a more convenient interface here with the `tx pull` command, downloading all translations as a batch. - -### Merge back existing translations - -If you want to backport translations onto release branches, simply run the `tx pull` command on multiple branches. This -assumes you're adhering to the following guidelines: - - - For significantly changed content of an entity, create a new entity key - - For added/removed placeholders, create a new entity - - Run the `i18nTextCollectorTask` with the `merge=true` option to avoid deleting unused entities - (which might still be relevant in older release branches) - -### Converting your language files from 2.4 PHP format to YML - -The conversion from PHP format to YML is taken care of by a module called -[i18n_yml_converter](https://github.com/chillu/i18n_yml_converter). - -## Download Translations from Transifex.com - -We are managing our translations through a tool called [transifex.com](https://www.transifex.com). Most modules are handled -under the "silverstripe" user, see -[list of translatable modules](https://www.transifex.com/user/profile/silverstripe/). - -Translations need to be reviewed before being committed, which is a process that happens roughly once per month. We're -merging back translations into all supported release branches as well as the `master` branch. The following script -should be applied to the oldest release branch, and then merged forward into newer branches: - -```bash -tx pull - -# Manually review changes through git diff, then commit -git add lang/* -git commit -m "Updated translations" -``` - -[notice] -You can download your work right from Transifex in order to speed up the process for your desired language. -[/notice] - -## JavaScript Translations - -SilverStripe also supports translating strings in JavaScript (see [i18n](/developer_guides/i18n)), but there's a -conversion step involved in order to get those translations syncing with Transifex. Our translation files stored in -`mymodule/javascript/lang/*.js` call `ss.i18n.addDictionary()` to add files. - -```js -ss.i18n.addDictionary('de', {'MyNamespace.MyKey': 'My Translation'}); -``` - -But Transifex only accepts structured formats like JSON. - -``` -{'MyNamespace.MyKey': 'My Translation'} -``` - -First of all, you need to create those source files in JSON, and store them in `mymodule/javascript/lang/src/*.js`. In your `.tx/config` you can configure this path as a separate master location. - -```ruby -[main] -host = https://www.transifex.com - -[silverstripe-mymodule.master] -file_filter = lang/.yml -source_file = lang/en.yml -source_lang = en -type = YML - -[silverstripe-mymodule.master-js] -file_filter = javascript/lang/src/.js -source_file = javascript/lang/src/en.js -source_lang = en -type = KEYVALUEJSON -``` - -Then you can upload the source files via a normal `tx push`. Once translations come in, you need to convert the source -files back into the JS files SilverStripe can actually read. This requires an installation of our -[buildtools](https://github.com/silverstripe-archive/silverstripe-buildtools). - -``` -tx pull -(cd .. && phing -Dmodule=mymodule translation-generate-javascript-for-module) -git add javascript/lang/* -git commit -m "Updated javascript translations" -``` - -# Related - - * [i18n](/developer_guides/i18n/): Developer-level documentation of Silverstripe's i18n capabilities - * [Contributing Translations](/contributing/translations): Information for translators looking to contribute translations of the SilverStripe UI. - * [translatable](https://github.com/silverstripe/silverstripe-translatable): DataObject-interface powering the website-content translations - * ["Translatable ModelAdmin" module](https://github.com/silverstripe-archive/silverstripe-translatablemodeladmin): An extension which allows translations of DataObjects inside ModelAdmin diff --git a/en/05_Contributing/15_Triage_Resources.md b/en/05_Contributing/15_Triage_Resources.md index 9b0c86bf2..28ec20a54 100644 --- a/en/05_Contributing/15_Triage_Resources.md +++ b/en/05_Contributing/15_Triage_Resources.md @@ -1,10 +1,10 @@ --- -title: Triage resources -summary: Canned responses and other resources used during triage +title: Triage and peer review +summary: Canned responses and other resources used during triage and peer review icon: users --- -# Triage resources +# Triage and peer review This page collates common resources that maintainers can use to efficiently and consistently manage incoming issues and PRs. @@ -15,27 +15,31 @@ This list helps to ensure that PRs are in a good state before merging. Ideally i initial triage, so that the contributor can check items off prior to the reviewer digging in. Some items may not be relevant to every PR, and can be crossed out on a case-by-case basis. -* [ ] The target branch is [correct](https://docs.silverstripe.org/en/4/contributing/code/#picking-the-right-version) -* [ ] All commits are relevant to the change (e.g. no debug statements or arbitrary linting) -* [ ] The commit messages follow [the contribution guidelines](https://docs.silverstripe.org/en/4/contributing/code/#commit-messages) -* [ ] The patch follows [the contribution guidelines](https://docs.silverstripe.org/en/4/contributing/code/) -* [ ] New features are covered with tests (back-end with unit tests, front-end with Behat) +* [ ] The target branch is correct + * For code, see [picking the right version](./code/#picking-the-right-version) + * For documentation, see [branches and commit messages](./documentation#branches-and-commit-messages). +* [ ] All commits are relevant to the purpose of the PR (e.g. no debug statements, unrelated refactoring, or arbitrary linting) + * Small amounts of additional linting are usually okay, but if it makes it hard to concentrate on the relevant + changes, ask for the unrelated changes to be reverted, and submitted as a separate PR. +* [ ] The commit messages follow our [commit message guidelines](./code/#commit-messages) +* [ ] The PR follows our [contribution guidelines](./code/) +* [ ] New features are covered with tests (back-end with unit/functional tests, front-end with Behat) * [ ] Any relevant User Help/Developer documentation is updated; for impactful changes, information is added to the - changelog for the intended release + changelog for the intended release * [ ] CI is green * [ ] At least one peer reviewer approved; no outstanding changes requested ## Canned Responses These are optional templates that can be [saved for re-use in GitHub](https://docs.github.com/en/github/writing-on-github/working-with-saved-replies), -serving as a starting point for working through common scenarios on issues and pull requests. Explainers are provided -below for each message to provide more context to affected contributors, and it often makes sense for the maintainer to +serving as a starting point for working through common scenarios on issues and pull requests. Context is provided +below for each message, and it often makes sense for the maintainer to expand upon the message with details specific to the given issue or PR. ### Stale PR warning -**Explainer:** In order to minimise the backlog of PRs that need attention from the core team, we periodically check in -on PRs that haven't seen any author activity for a month or more. We'll give you a heads up, and you'll have 2 weeks to +**Context:** In order to minimise the backlog of PRs that need attention from the core team, we periodically check in +on PRs that haven't seen any author activity for a while. We'll give you a heads up, and you'll a chance to progress the work or respond to any outstanding feedback. > This pull request hasn't had any activity for a while. Are you going to be doing further work on it, or would you @@ -43,29 +47,40 @@ progress the work or respond to any outstanding feedback. ### Stale PR closure -**Explainer:** If we don't hear back or see any changes within the 2 week timeframe, we'll close the PR out. +**Context:** If we don't hear back or see any changes for a while after being asked if more changes will be made, we'll close the PR. > 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. ### Enhancement Issue raised -**Explainer:** See the [linked documentation](https://docs.silverstripe.org/en/4/contributing/issues_and_bugs/#feature-requests) -for details. +**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. -> Thanks for your suggestion! Just to let you know we're closing this feature request as GitHub issues are not the best -> place to discuss potential enhancements. You can read more about this in the [contributing guide](https://docs.silverstripe.org/en/4/contributing/issues_and_bugs/#feature-requests), +> Thanks for your suggestion! As per our [contributing guide](./issues_and_bugs/#feature-requests) we don't typically +> accept feature requests as GitHub issues, but if you're willing to implement the feature in the near future we can +> leave the issue open to track discussion about it while you're working on it. +> +> Are you intending to implement this feature? + +### Enhancement Issue raised without intention to implement + +**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. + +> Just to let you know we're closing this feature request as GitHub issues are not the best +> place to discuss potential enhancements unless you're intending to implement the solution in the near future. +> You can read more about this in the [contributing guide](./issues_and_bugs/#feature-requests), > and you are welcome to raise new feature ideas on the [Silverstripe forum](https://forum.silverstripe.org/c/feature-ideas) > instead. ### Complex enhancement/new feature that doesn't fit core -**Explainer:** We generally try to avoid major additions to the core codebase, as they increase the maintenance burden +**Context:** We generally try to avoid major additions to the core codebase, as they increase the maintenance burden on the core team. Instead, we recommend pursuing major new features/enhancements as independent modules, which is possible in most cases due to the broad extensibility of the core APIs. Examples of high-value features that are developed as independent modules include -[dnadesign/silverstripe-elemental](https://github.com/dnadesign/silverstripe-elemental), +[silverstripe-terraformers/keys-for-cache](https://github.com/silverstripe-terraformers/keys-for-cache), +[dnadesign/silverstripe-elemental](https://github.com/silverstripe/silverstripe-elemental), [symbiote/silverstripe-gridfieldextensions](https://github.com/symbiote/silverstripe-gridfieldextensions), and [jonom/silverstripe-focuspoint](https://github.com/jonom/silverstripe-focuspoint). @@ -74,4 +89,4 @@ and [jonom/silverstripe-focuspoint](https://github.com/jonom/silverstripe-focusp > > If you’d like to take your idea further and share it with the community, we highly recommend turning your PR into an > open source module and posting about it in the appropriate community channels. See the docs on -> [how to create a module](https://docs.silverstripe.org/en/4/developer_guides/extending/modules/#create). +> [how to create a module](/developer_guides/extending/modules/#create). diff --git a/en/05_Contributing/17_Managing_Security_Issues.md b/en/05_Contributing/17_Managing_Security_Issues.md index eb0a09755..dc332f133 100644 --- a/en/05_Contributing/17_Managing_Security_Issues.md +++ b/en/05_Contributing/17_Managing_Security_Issues.md @@ -1,5 +1,5 @@ --- -title: Managing Security Issues +title: Managing security issues summary: This document highlights how the Silverstripe CMS security team handles security issues. icon: shield-alt --- @@ -10,7 +10,7 @@ This document aims to provide a high level overview of how the Silverstripe CMS ## Broad approach -While the process for handling security issues is publicly visible, only a limited number of participants are privy to the internal pre-disclosure discussions around specific vulnerabilities. +While the process for handling security issues is publicly visible, only a limited number of participants are privy to the internal pre-disclosure discussions around specific vulnerabilities. We aim to release security fixes with our regularly scheduled minor releases to minimise disruption to Silverstripe CMS projects. This allows security releases to go through our regular regression testing. We will usually hold back security fixes for a few weeks or months while we wait for the next scheduled release. @@ -20,7 +20,7 @@ If there's indication that a vulnerability is actively exploited in the wild or Silverstripe staff are granted access to review undisclosed security issues on a need-to-know basis and are bound by their employment contracts. Core committers not currently employed by Silverstripe are allowed to review undisclosed security issues after signing a non-disclosure agreement. -## Handling security issues confidentially +## Handling security issues confidentially This process is relevant when a potential vulnerability is reported confidentially and the Silverstripe CMS development team is in a position to prepare a patch prior to the public disclosure of the vulnerability. @@ -28,66 +28,78 @@ This process is usually started once someone [reports a security issue](issues_a ### When receiving a report +[hint] +Ensure the reporter is given a justification for all issues we conclude are not security vulnerabilities. +[/hint] + 1. An automated response is sent back to the reporter to acknowledge receipt of their vulnerability report. -2. Perform an initial assessment of the report. -3. [Create a issue in our private security repository](https://github.com/silverstripe-security/security-issues/issues/new) unless the report is obviously invalid. e.g. SPAM. -4. Clarify who picks up and owns the issue (assign in Github). - The owner can be separate from the developer resolving the issue, - their primary responsibility is to ensure the issue keeps moving through the process correctly. -5. If encrypted information or attachments are provided, attach them to the private security issue. -6. Reply to [security@silverstripe.org](mailto:security@silverstripe.org) ONLY (i.e. do not include the reporter in this reply) and provide a link to the private security issue. Keep most of the discussion on GitHub. -7. Perform a criticality assessment to determine how severe the issue is and if it can be replicated. +1. Perform an initial assessment of the report. If the report does not qualify as a security issue, reply to the reporter thanking them for their efforts and explaining that we won't be handling this as a security issue. + - If what was raised is a valid bug but not a valid security report, advise them to raise an issue on GitHub. + - If the report was spam, see [spam](#spam) below. +1. If the report is valid, [create a issue in our private security repository](https://github.com/silverstripe-security/security-issues/issues/new). + - Prefix the issue name with "[NO CVE REQUESTED YET]". + - If encrypted information or attachments are provided, attach them to the private security issue. + - Add the new issue to the "Triage" column on the [project board](https://github.com/silverstripe-security/security-issues/projects/1). +1. Reply to [security@silverstripe.org](mailto:security@silverstripe.org) ONLY (i.e. do not include the reporter in this reply) and provide a link to the private security issue. Keep most of the discussion on GitHub. +1. Clarify who picks up the issue (assign in GitHub). + - This is the person responsible for communicating with the reporter and applying for the CVE, etc. Usually this is whoever creates the issue. + - The person who implements a fix for the issue does not have to be the person initially assigned in GitHub. +1. Perform an assessment to determine how severe the issue is and if it can be replicated. - You may need to seek additional information from the reporter before completing the criticality assessment. - Validate the assessment with at least one other member of the security team before replying to the reporter with your conclusion. -8. Use the [CVSS Calculator](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator) to determine the issue severity. -9. Ensure the reporter is given a justification for all issues we conclude are not security vulnerabilities. -10. Add the new issue in the "Backlog" on the [project board](https://github.com/silverstripe-security/security-issues/projects/1). -11. Once the issue is confirmed, [create a draft security advisory](#creating-a-github-security-advisory) against the relevant GitHub repository. This will allow you to request a CVE. -12. Once a CVE has been assigned, add it to the Github issue and respond to the issue reporter. + - Add a comment to the GitHub issue with your findings, replications steps, and any suggested solutions. +1. Use the [CVSS Calculator](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator) to determine the issue severity. +1. Move the issue to the "Backlog" column on the [project board](https://github.com/silverstripe-security/security-issues/projects/1). +1. Once the issue is confirmed, [create a draft security advisory](#creating-a-github-security-advisory) against the relevant GitHub repository. +1. If the CVSS score is higher than 0.0, and it is not directly caused by an upstream dependency, request a CVE via the GitHub advisory UI. +1. Once a CVE has been assigned, add it to the GitHub issue and respond to the issue reporter. - Ask the reporter if they want to be credited for the disclosure and under what name. +[warning] +Make sure you read the [special circumstances](#special-circumstances) section below in case there are more or different steps you need to follow. +[/warning] ### Developing a fix - Move the issue into "In Progress" on the [project board](https://github.com/silverstripe-security/security-issues/projects/1) -- If the silverstripe-security GitHub organisation doesn't have a pre-existing private repo for the module that needs to be fixed, create one and push the public git history to it. You can not do a private fork of a public repo. -- Identify the oldest supported minor release where the vulnerability should be patched for each major release line. (see [Supported Versions](release_process/#supported-versions)) +- If the silverstripe-security GitHub organisation doesn't have a pre-existing private repo for the module that needs to be fixed, do not create a fork because you cannot create a private fork of a public repo. Instead create a new repo on the silverstripe-security account and push the public git history to it. +- Identify the oldest supported minor release where the vulnerability should be patched for each major release line. (see [minor release support timeline](/project_governance/minor_release_policy/#minor-release-support-timeline)). - Make sure the target branches on the private repo are up-to-date with the public repo branches. -- Create a fix for each supported major release line and open PRs against the appropriate branches on the private repo. +- Create a fix for each supported major release line and open PRs against the appropriate branches on the private repo. - Ensure that all security commit messages are prefixed with the CVE. E.g. "[CVE-2019-001] Fixed invalid XSS" - If there is no CVE assigned yet, use "[CVE-????-???]" for the prefix, and update it once a CVE is assigned. + - If we are not assigning a CVE for this issue, use the `SS-` style identifier (e.g. "[SS-2019-001]") as the prefix. - Once peer review is completed on the private PRs, do **not** merge it. The PRs should remain open until the fix is released publicly. ### Before release - For issues rated "high" or "critical" (CVSS of >=7.0), post a pre-announcement to the [security pre-announcement list](https://groups.google.com/a/silverstripe.com/forum/#!forum/security-preannounce). - It should include a basic "preannouncement description" which doesn't give away too much, - the CVSS score, and the CVE identifier. -- Create a draft page under [Open Source > Download > Security Releases](https://www.silverstripe.org/admin/pages/edit/show/794). - Populate it with the information from the [Github project board](https://github.com/silverstripe-security/security-issues/projects/1). -- Link to the individual silverstripe.org security advisory pages in the changelog. + It should include a basic "preannouncement description" which doesn't give away too much, the CVSS score, and the CVE identifier. +- Create a draft page under `Open Source > Download > Security Releases` on silverstripe.org. Populate it with the information from the security issue. - Update the _draft security advisory_ on GitHub to use the latest wording and link to the advisory on silverstripe.org. - Move the issue to "Awaiting Release" in the [project board](https://github.com/silverstripe-security/security-issues/projects/1) - + ### After release - Publish the security advisory release page on silverstripe.org. - Publish the security advisory on GitHub. This will also publish the CVE. -- Respond to the issue reporter with a link to the security advisory on the same discussion thread (cc security@silverstripe.org). -- Open a pull request to the [FriendsOfPHP/security-advisories](https://github.com/FriendsOfPHP/security-advisories) repository. +- Respond to the issue reporter with a link to the security advisory on the same discussion thread (cc ). +- Open a pull request to the [FriendsOfPHP/security-advisories](https://github.com/FriendsOfPHP/security-advisories/tree/master/silverstripe) repository. - Move the issue to "Done" in the [project board](https://github.com/silverstripe-security/security-issues/projects/1) +- Close the private pull request(s) and issue. ### Creating a GitHub security advisory GitHub security advisories allow you to request a CVE and attached them a CVSS score. A draft security advisory should be created against the repository where the vulnerability will be patched. If a vulnerability requires patches against multiple modules, aim to create the advisory against the module most directly affected. In the GitHub _draft security advisory_, we follow certain conventions on fields: + - **Affected product** should have one entry for each composer package affected by the vulnerability. If the patch is backported to older release lines, there should be entries for those older releases. - **Ecosystem** should always be `composer`. - **Package name** must match the package name in Packagist. - **Affected versions** must be a string representing a range of versions affected by the vulnerability. - **Patched versions** must list the versions where the vulnerability was/will be patched. -- **Severity** must be set to *Assess severity using CVSS* and the CVSS option must be specified in the calculator. +- **Severity** must be set to _Assess severity using CVSS_ and the CVSS option must be specified in the calculator. - **Common weakness enumerator (CWE)** should be left blank if no suitable option can be found in the list. - **CVE identifier** must be set to "Request CVE ID later" until we have had a CVE assigned. - **Title** and **Description** should be descriptive enough that people can evaluate the risk without being so specific that would-be-hackers can start exploiting them right away. @@ -100,7 +112,7 @@ These settings can be changed later, so if you are missing information when you Occasionally, some developers will open a public issue on GitHub reporting a vulnerability, either because they are unaware of the proper process or because they did not immediately grasp the security implication of the bug being reported. -In those situations, the security team will assess how likely it was that the vulnerability was widely noticed based on how long the issue was opened on GitHub, whether there were any interactions from other GitHub users, and how explicit the description was. If the risk of the vulnerability having been noticed is small, an owner on the Silverstripe GitHub organisation will delete the public facing issue and create a private one instead. +In those situations, the security team will assess how likely it was that the vulnerability was widely noticed based on how long the issue was opened on GitHub, whether there were any interactions from other GitHub users, and how explicit the description was. If the risk of the vulnerability having been noticed is small, an owner on the Silverstripe GitHub organisation will delete the public facing issue and create a private one instead - and attempt to contact the reporter to advise them of the correct procedure to follow in the future. If it's likely that the issue was noticed publicly, it should be handle as a zero-day vulnerability and patched as soon as possible. @@ -112,46 +124,47 @@ If it's likely that the issue was noticed publicly, it should be handle as a zer - People reporting vulnerabilities via Huntr are not always familiar with Silverstripe CMS. Don't assume that they have much context on what Silverstripe CMS is used for. - Take some time to review the reporter's profile to see how serious and reliable they are. - Validate what CVSS score the reporter has suggested for the issue. -- Once we "confirm" an issue in Huntr, it means that we agree the bug exists and that it's a vulnerability. Only confirm an issue if you have concluded that it is a valid security vulnerability that we will fix through the normal security process and have validated this conclusion with at least one other member of the security team. Security _enhancements_ should not be confirmed. -- By default, Huntr will issue CVEs for issues reported through their platform. We've disabled this functionality. -- Marked the issue as "fixed" in hunter once a patched has been released. +- Once we "confirm" an issue in Huntr, it means that we agree the bug exists and that it's a vulnerability. Only confirm an issue if you have concluded that it is a valid security vulnerability that we will fix through the normal security process and have validated this conclusion with at least one other member of the security team. Security _enhancements_ should not be marked as confirmed. +- By default, Huntr will issue CVEs for issues reported through their platform. We've disabled this functionality - follow the process in [when receiving a report](#when-receiving-a-report) to request a CVE. +- Mark the issue as "fixed" in hunter once a patched has been released. ### A vulnerability has been reported against a dependency of Silverstripe CMS Silverstripe CMS relies on many other dependencies which are outside of our control. Those dependencies will occasionally have vulnerabilities reported and patched against them. -When a vulnerability is disclosed against a Silverstripe CMS dependency, we generally do not consider this a vulnerability in Silverstripe CMS and will not issue a CVE for it. +When a vulnerability is disclosed against a downstream dependency of Silverstripe CMS, we generally do not consider this a vulnerability in Silverstripe CMS and will not issue a CVE for it. We will consider taking actions if: + - the vulnerability is compounded by the specific way the dependency is used within Silverstripe CMS or - a Silverstripe CMS constraint prevents the installation of a patched version of the dependency. As a general principle, Silverstripe CMS composer constraints do not preclude the installation of dependencies with known vulnerabilities. It is the responsibility of Silverstripe CMS project owners to regularly update these constraints and to review the risk posed by specific vulnerabilities. -### SPAM vulnerability report +## SPAM We receive a substantial amount of SPAM at our security email address. Those fall into 3 broad categories. -#### Straight up untargeted SPAM +### Straight up untargeted SPAM -Simply ignore these emails and mark them as SPAM in your email client. +Simply ignore these emails and mark them as SPAM in the mailing list. -#### Non-security requests +### Email that is not reporting a security vulnerability -Our security email is the only email address bots can find on our website. We get a lot of generic requests. e.g. _Your site is awesome, would you like me to contribute a guest post?_ +Bots can our security email address by crawling this documentation. As a result, we get a lot of generic requests. e.g. _Your site is awesome, would you like me to contribute a guest post?_ Provide a cursory response such as: -> This email address is only used to report potential security issues with Silverstripe CMS. +> This email address is only used to report potential security issues with Silverstripe CMS. Please do not send additional unrelated emails or your email address will be marked as spam. If more invalid requests are received from that sender, they should be blocked from the mailing list. -#### Low quality security reports +### Low quality security reports We get a lot of boiler plate vulnerability reports from individuals hoping to collect bounties. These requests are usually crafted to obscure their non-sensical nature. When dealing with this kind of request, provide a brief response explaining why the request is invalid and include some boiler plate language such as: -> Silverstripe does not operate a bug bounty program. +> Silverstripe does not operate a bug bounty program. Please do not send additional low quality security reports or your email address will be marked as spam. Consider blocking repeat offenders from the the mailing list. diff --git a/en/05_Contributing/index.md b/en/05_Contributing/index.md index 6f54e7410..b16ab9a4c 100644 --- a/en/05_Contributing/index.md +++ b/en/05_Contributing/index.md @@ -1,17 +1,16 @@ --- title: Contributing -summary: Any open source product is only as good as the community behind it. You can participate by sharing code, ideas, or simply helping others. No matter what your skill level is, every contribution counts. +summary: Any open source product is only as good as the community behind it. You can participate by sharing code, ideas, or simply helping others. No matter what your skill level is, every contribution counts. icon: heart --- ## House rules for everybody contributing to Silverstripe CMS - * Read over the Silverstripe CMS Community [Code of Conduct](/project_governance/code_of_conduct) - * Ask questions on the [forum](https://forum.silverstripe.org/) - * Make sure you know how to [raise good bug reports](issues_and_bugs) - * Everybody can contribute to SilverStripe! If you do, ensure you can [submit solid pull requests](code) -See our [high level overview on silverstripe.org](https://www.silverstripe.org/community/contributing-to-silverstripe/) -on how you can help out. Or, for more detailed guidance, read one of the following pages: +* Read over the Silverstripe CMS community [Code of Conduct](/project_governance/code_of_conduct) +* Ask questions on the [forum](https://silverstripe.org/community/forums) +* Make sure you know how to [raise good bug reports](issues_and_bugs) +* Everybody can contribute to SilverStripe! If you do, ensure you [submit solid pull requests](code) -[CHILDREN] +For more detailed guidance, read one of the following pages: +[CHILDREN] diff --git a/en/06_Project_Governance/03_Maintainer_Guidelines.md b/en/06_Project_Governance/03_Maintainer_Guidelines.md index b9a6d183e..17c549de6 100644 --- a/en/06_Project_Governance/03_Maintainer_Guidelines.md +++ b/en/06_Project_Governance/03_Maintainer_Guidelines.md @@ -104,13 +104,13 @@ First and foremost rule of a maintainer is to collaborate with other maintainers Triaging issues and pull requests involves review, applying labels, as well as closing invalid submissions. -Applying [labels](./code/#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”. +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](./code/#labels) + - 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) diff --git a/en/_images/contributing/docs-check-the-branch.png b/en/_images/contributing/docs-check-the-branch.png new file mode 100644 index 000000000..de1091b4c Binary files /dev/null and b/en/_images/contributing/docs-check-the-branch.png differ diff --git a/en/_images/contributing/docs-commit-message.png b/en/_images/contributing/docs-commit-message.png new file mode 100644 index 000000000..a2ebbc757 Binary files /dev/null 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 new file mode 100644 index 000000000..440699641 Binary files /dev/null and b/en/_images/contributing/docs-use-correct-branch.png differ