diff --git a/docs/source/developer-guidelines/contributing.md b/docs/source/developer-guidelines/contributing.md index 04446bf2db..f1d04cf34d 100644 --- a/docs/source/developer-guidelines/contributing.md +++ b/docs/source/developer-guidelines/contributing.md @@ -9,8 +9,16 @@ myst: # Contributing to Volto -You may have an issue to report, make a feature request, report a security vulnerability, or you want to create a pull request. -You have come to the right place to learn how to do so. +First read {doc}`plone:contributing/index`. +Volto follows those guidelines with a few specific variations, as described in this chapter. + +If after reading this you become hesitant, don't worry. +You can always create a pull request, mark it as "Draft", and improve the following points later, requesting help from the community. + + +## Sign and return the Plone Contributor Agreement + +See {ref}`Plone Contributor Agreement `. ## Reporting an issue or making a feature request @@ -22,65 +30,43 @@ When in doubt, create one in the [CMFPlone issue tracker](https://github.com/plo In your report, please specify a few things: -- What are the steps to reproduce the problem? -- What do you expect when you follow those steps? -- What do you observe? -- Which Plone version are you using? -- Include relevant screenshots, error messages, and stack traces. +- What are the steps to reproduce the problem? +- What do you expect when you follow those steps? +- What do you observe? +- Which Plone version are you using? +- Include relevant screenshots, error messages, and stack traces. + ## Branch policy ```{include} ./branch-policy.md ``` -## Sign and send us the Plone Contributors Agreement - -You must sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement) to contribute code and documentation to any Plone project. -This means that we can NOT accept pull requests from you from any location until you do this. - -## First Time Contributors: work from a fork +## Translations -When we have received the Plone Contributor Agreement and it has been process by a community member, you will be added to the Plone organisation and added to the Contributors Team on GitHub. -You can create issues, add comments to existing issues, and discuss the development of Plone with others. -Creating branches and editing code on our main repositories is restricted and granted to members who have been active in the Plone community for a while and have shown continued interest to contributing. +All text that can be shown in a browser must be translatable. +Please mark all such strings as translatable as defined in the [i18n guide](../recipes/i18n.md). -- First, verify that your issue is valid by creating it and discussing it with other developers. -- Then, create a fork of the repo in your own workspace, work on your code and make commits. -- When you want to run our code quality checks, create a Pull Request from your repo/branch to the main repository. -- As a security measure, the first run of code Quality checks need to be [approved by a member in our Developers Team](https://docs.github.com/en/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks) -- A Developer with full access to the workflow will need to review and approve your Pull request. -Please be aware that as long as you are working from a fork, you are the only developer being able to commit to your branch. -Collaboration between developers on bigger pull requests is more efficient when these are done on branch on the main repo. -Therefore: as your first time contribution don't choose a too big problem to solve. -Pick something that you can fix or complete from start to end. +## Volto change log entry +Volto requires that you include a change log entry or news item with your contribution. +Your attribution must be in the format of `@github_username`. +```{seealso} +For details see {ref}`contributing-change-log-label`. +``` -## Documenting your changes - -All pull requests must include a `towncrier` news item. -This is a file that is placed in the root of the repository directory at `/news`. -Its format must be `###.type`, where `###` is the referenced GitHub issue or pull request number, `.` is the literal extension delimiter, and `type` is one of the following strings. -- `breaking` for breaking changes -- `bugfix` for bug fixes -- `documentation` for documentation -- `feature` for new features -- `internal` for internal changes +## Documenting your changes If the feature includes a breaking change, you must include instructions for how to upgrade in the [upgrade guide](../upgrade-guide/index.md). -All text that can be shown in a browser must be translatable. Please mark all such -strings as translatable as defined in the [i18n guide](../recipes/i18n.md). - -## Code Quality +## Code quality All pull requests must pass tests, documentation builds, and other code quality checks. -Developers are strongly encouraged to run these checks locally before creating a pull request. -Contributors without full Developer access will need to create a Pull request first and get approval for their first PR from a Developer. These checks are enforced automatically on every pull request, so you might as well save time and frustration by doing these checks locally first. Specifically: @@ -88,9 +74,3 @@ Specifically: - {doc}`./linting` - {doc}`./testing` - {doc}`./acceptance-tests` - - -If after reading this you become hesitant, don't worry. -You can always create a pull request, mark it as "Draft", and improve the above points later, requesting help from the community. - -Welcome to the Plone community, and thank you for contributing!