From 7617f9192271097f6295093f917e493eaf46a62d Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 20 Sep 2022 10:37:16 +0200 Subject: [PATCH 1/7] initial commit --- CONTRIBUTING.md | 43 +++++++++++++++++++------------------------ 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa36cf03e1..d582efd9c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,43 +6,40 @@ All efforts to contribute are highly appreciated, we recommend you talk to a mai ## Open Development & Community Driven -Strapi is an open-source project. See the [LICENSE](https://github.com/strapi/documentation/blob/main/LICENSE) file for licensing information. All the work done is available on GitHub. +Strapi is an open-source project. See the [LICENSE](https://github.com/strapi/documentation/blob/main/LICENSE) file for licensing information. All of the work is available on GitHub. The core team and the contributors send pull requests which go through the same validation process. -## Documentation Requests +## Code of Conduct -Requests for new documentation are highly encouraged, this is not limited to new additions but also changes or more information requested on existing documentation. Please use our [request documentation](https://github.com/strapi/documentation/issues/new?template=DOC_REQUEST.md&title%5B%5D=REQUEST) issue template. +This project and everyone participating in it are governed by the [Strapi Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold the code. -## Code of Conduct +## Documentation Requests -This project and everyone participating in it are governed by the [Strapi Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please read the [full text](CODE_OF_CONDUCT.md) so that you can read which actions may or may not be tolerated. +Requests for new documentation are highly encouraged, this is not limited to new additions but also changes or more information requested on existing documentation. Please use our [request documentation](https://github.com/strapi/documentation/issues/new?template=DOC_REQUEST.md&title%5B%5D=REQUEST) issue template. If you are requesting documentation, please feel free to open a pull request. ## Bugs -We are using [GitHub Issues](https://github.com/strapi/documentation/issues) to manage our public bugs. Before submitting an issue you need to make sure: +Bug reports help to improve the documentation. Please use our [Documentation Bug Report](https://github.com/strapi/documentation/issues/new?template=BUG_REPORT.yml) template to report documentation bugs. Before submitting an issue: -- Checked for any existing pull requests that may address the same issue -- Checked for any open issues related to your issue, if so, please provide context on that issue -- Follow the issue template and try to fill out as much information as you can - - Issues not following the templates **will be closed** - - You may update the closed issue with the required information and it will be reopened -- The issue is with the Strapi **documentation only**, code issues should be directed at the main [strapi/strapi](https://github.com/strapi/strapi) repo issues -- If you are requesting documentation, please do feel free to make a pull request - - Documentation requests will be handled when we have free room within our roadmap - - Open requests **are not handled** in a "first come, first serve" basis, they are handled on a "best-effort" depending on the time required to produce -- Do not ask technical questions about how to do something - - Questions should be directed at the following resources - - Open a Q&A thread on our [Official Forum](https://forum.strapi.io) - - Talk with other community members on our [Community Discord](https://discord.strapi.io) +- Check for existing pull requests that may address the same issue. +- Check for related open issues, if so, please provide context on the existing issue. +- Follow the issue template and fill out as much information as you can. +- Verify The issue is with the Strapi **documentation only**, code issues should be directed at the main [strapi/strapi](https://github.com/strapi/strapi) repo issues. + +Technical questions should be directed at the following resources: -Please note that rude or impolite comments on issues that violate our [Code of Conduct](./CODE_OF_CONDUCT.md) will be deleted and issues that violate the COC will be closed. +- Open a Q&A thread on our [Official Forum](https://forum.strapi.io) +- Talk with other community members on our [Community Discord](https://discord.strapi.io) --- ## Submitting a Pull Request -The core team will review your pull request and will either merge it, request changes to it, or close it. +The core team will review your pull request and will either merge it, request changes to it, or close it. You can open a documentation pull request by either: + +- following the `Improve this page` link at the bottom of each documentation page to directly edit in GitHub, +- forking the `documentation` repository and working locally. ### Setup and pull request creation @@ -153,8 +150,6 @@ The pull request will be validated once the contribution ticks all the boxes. At #### Deployment -Once your pull request is validated and merged, it will be deployed with the next batch of merged pull requests. The Strapi Documentation team only deploys the documentation on Wednesdays, but not every week. +When your pull request is validated and merged, it will be assigned to a Milestone with a deployment version and date. The Strapi Documentation team typically deploys the documentation on Wednesdays, but not every week. Every documentation deployment is communicated through a message in [the "News" section of the Strapi forum](https://forum.strapi.io/c/news/5). - - From dec933f592f60fae0d0e8c656050140eb694cf12 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 20 Sep 2022 15:32:28 +0200 Subject: [PATCH 2/7] reword and shorten --- CONTRIBUTING.md | 37 +++++++++++-------------------------- 1 file changed, 11 insertions(+), 26 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d582efd9c6..8932d3c60c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,7 +43,7 @@ The core team will review your pull request and will either merge it, request ch ### Setup and pull request creation -Follow the procedure below to contribute to the Strapi documentation. +The following procedure allows you to work locally on the Strapi documentation. 1. Fork the `documentation` repository. 2. Clone your forked `documentation` repository. @@ -83,7 +83,7 @@ Follow the procedure below to contribute to the Strapi documentation. git pull ``` -6. Create your own branch, based on either `main` or `v[x]` , on which you will work on your documentation contribution. Make sure the name of your branch indicates both the type of documentation and the topic. +6. Create your own branch, based on either `main` or `v[x]` , to work on your documentation contribution. Make sure your branch name indicates both the type of documentation and the topic. ```bash # developer documentation @@ -115,41 +115,26 @@ Follow the procedure below to contribute to the Strapi documentation. The project is now up and running at http://localhost:8080 and you should be able to access it in your browser. - You are now ready to contribute to the Strapi documentation! 🚀 🤗 Make sure to follow the [12 Rules of Technical Writing](https://handbook.strapi.io/user-success-manual/12-rules-of-technical-writing) and the [Strapi Documentation Style Guide](https://handbook.strapi.io/user-success-manual/strapi-documentation-style-guide) when writing your documentation contribution. These documents are meant to help you write a contribution that fits the whole Strapi documentation and make the reviewing process easier and quicker. When you are finished writing, create a pull request from your forked repository to the original `documentation` repository (see [the GitHub docs](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) for more information). -✋ To be able to submit your contribution, you must sign the CLA (Contributor License Agreement), directly via GitHub (see [our dedicated blog post](https://strapi.io/blog/switching-from-dco-to-cla) for more information). +✋ Sign the CLA (Contributor License Agreement), directly via GitHub (see [our dedicated blog post](https://strapi.io/blog/switching-from-dco-to-cla) for more information). ### Pull request review and management -Read the information below to know how your contribution will be handled by the Strapi Documentation team until it is merged and deployed. - -#### Handling - -When a new pull request is submitted in the Strapi `documentation` repository, it is handled in the following week, meaning that the Strapi team: - -- acknowledges the new pull request, leaving a 👀 reaction on the description -- tags the pull request, to indicate the type of documentation that is being updated, and optionally the level of priority for the contribution -- assigns the pull request to a member of the Strapi Documentation team, who will be in charge of the reviewing and merging - -#### Review - -Once all of the handling steps are done by the Strapi team, you can expect your pull request to be reviewed in the next week or so. - -Here is what the Strapi Documentation team will review in your pull request: - -- The accuracy and coherence of the contribution, by testing any new piece of code or action for example, -- The quality of the technical writing, to make sure it is proper technical documentation that is easy to understand (see [12 Rules of Technical Writing](https://www.notion.so/12-Rules-of-Technical-Writing-c75e080e6b19432287b3dd61c2c9fa04)) -- The fit of the contribution among the rest of the Strapi documentation (see [Strapi Documentation Style Guide](https://www.notion.so/Strapi-Documentation-Style-Guide-b9c21387732741ed8b0a3f9701612577)) +The pull request review process and timeline are based on the availability of Strapi's Documentation team to handle community contributions. The workflow is: -The pull request will be validated once the contribution ticks all the boxes. At least the validation of the Strapi Documentation team member in charge of the pull request is necessary for it to be merged. +1. The pull request is assigned to a member of the Documentation team. +2. At least 1 member of the Documentation team will review the pull request for: -#### Deployment +- accuracy, +- quality, +- alignment with the documentation scope and roadmap. -When your pull request is validated and merged, it will be assigned to a Milestone with a deployment version and date. The Strapi Documentation team typically deploys the documentation on Wednesdays, but not every week. +3. Reviewers will either approve, ask for changes, or reject the pull request. +4. Accepted pull requests will be merged and deployed as part of the regular documentation deployments on Wednesdays, but not every week. Every documentation deployment is communicated through a message in [the "News" section of the Strapi forum](https://forum.strapi.io/c/news/5). From 72241e7e0271c0892d6c2c9a515008056acb111d Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 20 Sep 2022 16:36:49 +0200 Subject: [PATCH 3/7] minor text, spacing and punctuation improvements --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8932d3c60c..e2347a584a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,7 +62,7 @@ The following procedure allows you to work locally on the Strapi documentation. cd documentation/docs/user-docs ``` -4. Choose the branch from which to work: either `main` for a contribution on the latest, current version or Strapi ; or `v[x]` for a contribution on a previous version of Strapi. +4. Choose the branch from which to work: either `main` for a contribution on the current version of Strapi or `v[x]` for a contribution on a previous version of Strapi. ```bash #current version of Strapi (i.e. v4) @@ -83,7 +83,7 @@ The following procedure allows you to work locally on the Strapi documentation. git pull ``` -6. Create your own branch, based on either `main` or `v[x]` , to work on your documentation contribution. Make sure your branch name indicates both the type of documentation and the topic. +6. Create your branch, based on either `main` or `v[x]`, to work on your documentation contribution. Make sure your branch name indicates both the type of documentation and the topic. ```bash # developer documentation From 0d4364a836093e7c05eefabb9e5c60fe5f97154a Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Tue, 20 Sep 2022 16:48:11 +0200 Subject: [PATCH 4/7] minor text improvements --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2347a584a..3bc7607bae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,9 +25,9 @@ Bug reports help to improve the documentation. Please use our [Documentation Bug - Check for existing pull requests that may address the same issue. - Check for related open issues, if so, please provide context on the existing issue. - Follow the issue template and fill out as much information as you can. -- Verify The issue is with the Strapi **documentation only**, code issues should be directed at the main [strapi/strapi](https://github.com/strapi/strapi) repo issues. +- Verify the issue is only with the Strapi documentation, code issues should be directed at the main [strapi/strapi](https://github.com/strapi/strapi) repository. -Technical questions should be directed at the following resources: +Technical questions should be asked using the following resources: - Open a Q&A thread on our [Official Forum](https://forum.strapi.io) - Talk with other community members on our [Community Discord](https://discord.strapi.io) @@ -36,9 +36,9 @@ Technical questions should be directed at the following resources: ## Submitting a Pull Request -The core team will review your pull request and will either merge it, request changes to it, or close it. You can open a documentation pull request by either: +The core team will review your pull request and will either merge, request changes, or comment and close it. You can open a documentation pull request by: -- following the `Improve this page` link at the bottom of each documentation page to directly edit in GitHub, +- clicking the `Improve this page` link at the bottom of any documentation page to directly edit in GitHub, - forking the `documentation` repository and working locally. ### Setup and pull request creation @@ -125,7 +125,7 @@ When you are finished writing, create a pull request from your forked repository ### Pull request review and management -The pull request review process and timeline are based on the availability of Strapi's Documentation team to handle community contributions. The workflow is: +The pull request review process and timeline are based on the availability of Strapi's Documentation team to handle community contributions. The workflow is: 1. The pull request is assigned to a member of the Documentation team. 2. At least 1 member of the Documentation team will review the pull request for: From 07e8cea754eb677bf9eb4de2caf8d7a9f5dbf1bb Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 26 Sep 2022 08:17:54 +0200 Subject: [PATCH 5/7] minor formatting changes --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3bc7607bae..17466bc62b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,18 +30,18 @@ Bug reports help to improve the documentation. Please use our [Documentation Bug Technical questions should be asked using the following resources: - Open a Q&A thread on our [Official Forum](https://forum.strapi.io) -- Talk with other community members on our [Community Discord](https://discord.strapi.io) +- Engage with other community members on our [Community Discord](https://discord.strapi.io) --- ## Submitting a Pull Request -The core team will review your pull request and will either merge, request changes, or comment and close it. You can open a documentation pull request by: +The core team reviews community pull requests and either merges, requests changes, or comments and closes the pull request. You can open a documentation pull request by: - clicking the `Improve this page` link at the bottom of any documentation page to directly edit in GitHub, - forking the `documentation` repository and working locally. -### Setup and pull request creation +### Setup and write locally The following procedure allows you to work locally on the Strapi documentation. @@ -117,6 +117,8 @@ The following procedure allows you to work locally on the Strapi documentation. You are now ready to contribute to the Strapi documentation! 🚀 +### Write technical documentation + 🤗 Make sure to follow the [12 Rules of Technical Writing](https://handbook.strapi.io/user-success-manual/12-rules-of-technical-writing) and the [Strapi Documentation Style Guide](https://handbook.strapi.io/user-success-manual/strapi-documentation-style-guide) when writing your documentation contribution. These documents are meant to help you write a contribution that fits the whole Strapi documentation and make the reviewing process easier and quicker. When you are finished writing, create a pull request from your forked repository to the original `documentation` repository (see [the GitHub docs](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) for more information). @@ -130,9 +132,9 @@ The pull request review process and timeline are based on the availability of St 1. The pull request is assigned to a member of the Documentation team. 2. At least 1 member of the Documentation team will review the pull request for: -- accuracy, -- quality, -- alignment with the documentation scope and roadmap. + - accuracy, + - quality, + - alignment with the documentation scope and roadmap. 3. Reviewers will either approve, ask for changes, or reject the pull request. 4. Accepted pull requests will be merged and deployed as part of the regular documentation deployments on Wednesdays, but not every week. From 135cea1af87d24c5f5e2a9e137e142b162c6f994 Mon Sep 17 00:00:00 2001 From: Shaun Brown Date: Mon, 26 Sep 2022 08:32:29 +0200 Subject: [PATCH 6/7] structure improvements --- CONTRIBUTING.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17466bc62b..4dcfd691f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ Technical questions should be asked using the following resources: --- -## Submitting a Pull Request +## Pull Requests The core team reviews community pull requests and either merges, requests changes, or comments and closes the pull request. You can open a documentation pull request by: @@ -119,22 +119,25 @@ You are now ready to contribute to the Strapi documentation! 🚀 ### Write technical documentation -🤗 Make sure to follow the [12 Rules of Technical Writing](https://handbook.strapi.io/user-success-manual/12-rules-of-technical-writing) and the [Strapi Documentation Style Guide](https://handbook.strapi.io/user-success-manual/strapi-documentation-style-guide) when writing your documentation contribution. These documents are meant to help you write a contribution that fits the whole Strapi documentation and make the reviewing process easier and quicker. +For lengthier contributions, we provide general guidelines that can help you write clear and concise documentation: -When you are finished writing, create a pull request from your forked repository to the original `documentation` repository (see [the GitHub docs](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) for more information). +- The [12 Rules of Technical Writing](https://handbook.strapi.io/user-success-manual/12-rules-of-technical-writing) gives an overview of how to structure and write clear documentation. +- The [Strapi Documentation Style Guide](https://handbook.strapi.io/user-success-manual/strapi-documentation-style-guide) has formatting guidelines and how to implement formatting in markdown files. + +When you are finished writing, create a pull request from your forked repository to the original `documentation` repository (see [the GitHub docs](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) for more information) or use the _Create a new branch for this commit and start a pull request_ option if you are using the GitHub web browser interface (see [the GitHub docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)). ✋ Sign the CLA (Contributor License Agreement), directly via GitHub (see [our dedicated blog post](https://strapi.io/blog/switching-from-dco-to-cla) for more information). -### Pull request review and management +### Review and management of pull requests The pull request review process and timeline are based on the availability of Strapi's Documentation team to handle community contributions. The workflow is: 1. The pull request is assigned to a member of the Documentation team. 2. At least 1 member of the Documentation team will review the pull request for: - - accuracy, - - quality, - - alignment with the documentation scope and roadmap. +- accuracy, +- quality, +- alignment with the documentation scope and roadmap. 3. Reviewers will either approve, ask for changes, or reject the pull request. 4. Accepted pull requests will be merged and deployed as part of the regular documentation deployments on Wednesdays, but not every week. From cfea77a5c33656f679b1b402bcb03d054e8cf682 Mon Sep 17 00:00:00 2001 From: Shaun Brown <97027841+StrapiShaun@users.noreply.github.com> Date: Tue, 27 Sep 2022 13:57:31 +0200 Subject: [PATCH 7/7] Update CONTRIBUTING.md Co-authored-by: Pierre Wizla --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4dcfd691f2..7ec0d7f595 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -140,6 +140,6 @@ The pull request review process and timeline are based on the availability of St - alignment with the documentation scope and roadmap. 3. Reviewers will either approve, ask for changes, or reject the pull request. -4. Accepted pull requests will be merged and deployed as part of the regular documentation deployments on Wednesdays, but not every week. +4. Accepted pull requests will be merged and deployed as part of the regular documentation deployments on Wednesdays every 2 weeks. Every documentation deployment is communicated through a message in [the "News" section of the Strapi forum](https://forum.strapi.io/c/news/5).