You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Nov 19, 2024. It is now read-only.
Copy file name to clipboardExpand all lines: .github/CONTRIBUTING.md
+71-41Lines changed: 71 additions & 41 deletions
Original file line number
Diff line number
Diff line change
@@ -4,77 +4,106 @@ Share your knowledge with the community by contributing to Magento DevDocs!
4
4
You can contribute by creating an issue or pull request (PR) on our [DevDocs](https://github.com/magento/devdocs) GitHub repository.
5
5
We welcome all types of contributions; from minor typo fixes to new topics.
6
6
7
-
Magento's tech writer team and [Community Maintainers](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributors.html#/community-maintainers) review issues and pull requests on a regular basis, and we do our best to address all issues as soon as possible.
8
-
Working through the backlog takes time, though, so we appreciate your patience.
7
+
DevDocs staff members and [Community Maintainers](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributors.html#/community-maintainers) review issues and pull requests on a regular basis. We do our best to address all issues as soon as possible, but working through the backlog takes time. We appreciate your patience.
9
8
10
9
## Rewards for contributions
11
10
12
11
DevDocs works with Magento Community Engineering teams and projects.
13
-
As you contribute PRs, you gain [Contribution Points](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#points). We track [Contributors](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributors.html#/individual-contributors) and [Maintainers](https://devdocs.magento.com/guides/v2.3/contributor-guide/maintainers.html) with Community Engineering.
12
+
As you contribute PRs, you gain [Contribution Points](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#points).
14
13
15
14
If you write and contribute a full topic, we will add your name (or your company's name) at the top of the DevDocs page and link it to your blog or website!
16
15
17
-
## Get started
16
+
## Get started
18
17
19
18
20
19
21
-
1. Make sure you have a [GitHub account](https://github.com/signup/free) with [Two-Factor Authentication](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#two-factor)(2FA) to your account. Partners are required to add 2FA protection when contributing to Magento repositories.
22
-
1. Sign the [Magento Contributor Agreement](https://magento.com/content/magento-contributor-agreement).
20
+
1. Make sure you have a [GitHub account](https://github.com/signup/free).
21
+
22
+
**Note for partners:** Add [2FA](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#two-factor) protection when contributing to Magento repositories.
23
+
23
24
1.[Fork](https://help.github.com/articles/fork-a-repo/) the [DevDocs repository](https://github.com/magento/devdocs). Remember to [sync your fork](https://help.github.com/articles/syncing-a-fork/) and update branches as needed.
24
25
1. Review the [DevDocs guidelines](#contribution-guidelines).
25
26
26
-
## Contribute docs
27
+
## Contribute documentation
28
+
29
+
The following diagram shows the contribution workflow:
1. Create a new branch on your fork. Use a name that best describes the work, or references a GitHub issue number.
31
-
1. Edit or create markdown (`.md`) files in your branch.
32
-
1. When ready, push your branch to your fork.
33
-
1. Create a PR to the [magento/devdocs repo](https://github.com/magento/devdocs). Fill out as much info as possible and link any GitHub issues.
33
+
**Tip!** If you are not sure where to start contributing, search for issues with the [`help wanted`](https://github.com/magento/devdocs/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22), [`good first issue`](https://github.com/magento/devdocs/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), and [`groomed`](https://github.com/magento/devdocs/issues?q=is:issue+is:open+label:%22groomed%22) labels. These issues receive higher priority for processing.
34
34
35
-
The DevDocs team and Maintainers will review the PR and help with formatting and navigation.
35
+
### Create a branch
36
36
37
+
1. Create a new branch from your fork using a name that best describes the work or references a GitHub issue number.
38
+
1. Edit or create markdown (`.md`) files in your branch.
39
+
1. Push your branch to your fork.
37
40
38
-
**Note:** If you have not signed the [Magento Contributor Agreement](https://magento.com/content/magento-contributor-agreement), the PR provides a link. We require a signed form and agreement to the terms for contribution.
41
+
### Create a pull request
39
42
40
-
**Tip!** If you are not sure where to start contributing, check out our GitHub issues labeled [help wanted](https://github.com/magento/devdocs/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and [good first issue](https://github.com/magento/devdocs/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
43
+
1. Create a pull request to the [magento/devdocs](https://github.com/magento/devdocs) repository.
41
44
42
-
## Contribution guidelines
45
+
In general, you should use `master` as the base branch when creating a PR. If your contribution is related to a release that is in progress, use a version-specific integration branch, such as `develop`.
46
+
47
+
1. Complete the pull request template.
43
48
44
-
Write content using [Kramdown](https://kramdown.gettalong.org/), which is a simple markup language. We use Kramdown, Liquid, and [Jekyll](https://jekyllrb.com/) to generate a static site hosted through [GH Pages](https://help.github.com/articles/what-is-github-pages/). Check [Templates](#templates) for examples of styles and markdown.
49
+
**We will close your pull request if you do not complete the template.**
45
50
46
-
You can update existing or add new topics in their respective Magento 2 versioned directories (2.1, 2.2, 2.3, and onward). If you need help finding a directory for your content, we can help in your PR.
51
+
1. After creating a pull request, a DevDocs staff member or maintainer will review it and may ask you to make revisions.
52
+
53
+
**We will close your pull request if you do not respond to feedback in two weeks.**
54
+
55
+
**Note:** If you have not signed the [Magento Contributor Agreement](https://magento.com/content/magento-contributor-agreement), the pull request provides a link. Magento requires a signed form and agreement to the terms for contribution.
56
+
57
+
## Contribution guidelines
47
58
48
59
The following guidelines may answer most of your questions and help you get started:
49
60
50
-
1. Check [existing pull requests](https://github.com/magento/devdocs/pulls) and make sure you are not duplicating work!
51
-
1. For large contributions or changes that include multiple files, [open an issue](#report-an-issue) and discuss it with us first. This may further prevent duplicate or unnecessary effort.
52
-
1. Familiarize yourself with the existing documentation. Look through and search the guides to decide where to add your topics.
61
+
- Write content using Markdown. See the [Templates](#templates) section for examples.
62
+
- Review existing [pull requests](https://github.com/magento/devdocs/pulls) and [issues](https://github.com/magento/devdocs/issues) to avoid duplicating work.
63
+
- For large contributions, or changes that include multiple files, [open an issue](#report-an-issue) and discuss it with us first. This helps prevent duplicate or unnecessary work.
64
+
- Do not make global find-and-replace changes without first creating an issue and discussing it with us. Global changes can have unintended consequences.
65
+
- Combine multiple small changes (such as minor editorial and technical changes) into a single pull request. This helps us efficiently and effectively facilitate your contribution.
66
+
- Familiarize yourself with the organization and conventions of our existing documentation before creating a pull request. Changes that are consistent with our style and conventions have a higher acceptance rate.
53
67
54
-
- The DevDocs team can find the best home for your new topics and add it to the navigation.
55
-
- If a topic has a symlink, you can remove it with Git commands and add a new file. Copy and paste a previous version of the topic to get started.
68
+
-If you need to update the site navigation, ask for help in Slack ([#devdocs](https://magentocommeng.slack.com/messages/CAN932A3H)).
69
+
-We use symbolic links for topics that are the same across versions of Magento. Remove the symbolic link and add a new file if your changes are unique to a specific version. Copy and paste a previous version of the topic to get started.
- Make sure that you update the correct version(s) of documentation (v2.1, v2.2, v2.3). If you are not sure what directory to put your content in, just do your best. We can help re-locate it (if necessary) during the review process.
82
+
- Review your work for basic typos, formatting errors, or ambiguous sentences before opening a pull request.
83
+
- Revise pull requests according to review feedback. We will close pull requests that require an inordinate amount of time to review and process (especially for minor changes) if you fail to make revisions according to review feedback.
84
+
- Do not directly contact DevDocs team members or maintainers on Slack to review your pull request unless it has been open for more than five days. We have a process and queue for pull requests that everyone must follow.
58
85
59
-
Focus on the content with useful information, code samples, and important notes for your fellow Magento developers and community members. Don't forget to review your work for typos, formatting errors, or sentences that need clarifying before opening a pull request.
86
+
## Tips for writing content
60
87
61
88
Use the following guidelines to help you with the writing process:
62
89
63
-
- Define the goal of your topic. What exactly do you want to teach the reader?
64
-
- Make the title of your topic reflect the content.
65
-
- Keep your sentences concise and try to separate conceptual information from procedural steps.
66
-
- Remember to use active voice (not passive), write in the present tense, and use a friendly tone in second person. For example, _"The log captures commands, output..."_.
67
-
- Use notes to alert readers about important details.
68
-
- Use cross-references to other topics if appropriate. We can help you with the syntax if it is not clear. The template provides an example you can use.
69
-
- Need help with markdown? See our [templates](#templates).
90
+
- Focus your efforts on providing useful information for your fellow Magento developers and community members. For example, consider providing or revising code samples, important notes, and clarifying vague or ambiguous content.
91
+
- Define the goal of your topic. What exactly do you want to teach the reader?
92
+
- Make the title of your topic reflect the content.
93
+
- Keep your sentences concise. Separate conceptual information from procedural steps.
94
+
- Batch several small changes into a single pull request (instead of separate ones) to ensure your contributions are approved and merged quickly. Have several typo fixes across several areas of documentation? Combine them into a single PR.
95
+
- Remember to write in present tense, use the second person, and use active voice (not passive). For example, _"The log captures commands, output..."_.
96
+
- Use notes to alert readers about important details.
97
+
- Use cross-references to other topics sparingly. We can help you with the syntax if it is not clear. The template provides an example you can use.
98
+
- Need help with markdown? See our [templates](#templates).
70
99
71
-
### Preview your work on local
100
+
### Review changes locally
72
101
73
-
Optional. To preview your changes in HTML output, follow the instructions in the [README](https://github.com/magento/devdocs/blob/master/README.md) to build the devdocs site locally using Jekyll.
102
+
_(Optional)_ To review your changes in HTML output, follow the instructions in the [README](https://github.com/magento/devdocs/blob/master/README.md) to build the devdocs site locally using Jekyll.
74
103
75
104
### Templates
76
105
77
-
We provide templates to help you started writing new content and understanding markdown formatting:
106
+
We provide templates to help you get started writing new content and understanding Markdown formatting:
78
107
79
108
- **General topic template** - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/basic_template.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html): This is a template for writing any topic with example formats and styles.
80
109
- **Tutorial templates**: These templates provide example formats and styles for step-by-step instructions (like how-tos). Each file adds navigation buttons when content is generated. Templates include:
@@ -93,22 +122,23 @@ title: Continue with your installation
93
122
---
94
123
```
95
124
96
-
97
125
> Key-value pair reference:
98
126
99
127
| Property | Description |
100
128
| ------------- | ---------- |
101
-
|`group`| Defines the topic's guide. Use the table of contents `.yml` file name. This loads your left-side navigation. We will help during the PR process to add new files to the `.yml` file. |
102
-
|`title`| Sets the title of the page in the HTML meta and the main title on the page. |
129
+
| `group` | Defines the topic's guide or section. Use the table of contents `.yml` file name. This loads your left-side navigation. We will help during the PR process to add new files to the `.yml` file. |
130
+
|`title`| Sets the title of the page in the HTML metadata and the main title on the page. |
103
131
104
132
## Report an issue
105
133
106
-
If you find a typo or errors in Magento DevDocs, you can either fix it with a pull request (as described above) or you can report it by creating an issue in the DevDocs GitHub repository.
107
-
Enter as much information as you can including content corrections, steps to reproduce, command or code updates, or questions for clarifications.
134
+
If you find a typo or errors in Magento DevDocs, you can either fix it with a pull request (as described above) or you can report it by creating an issue in the DevDocs GitHub repository.
135
+
136
+
You must complete the issue template. We will close your issue if you fail to complete the template. Enter as much information as you can, including content corrections, steps to reproduce, command or code updates, or questions for clarifications.
137
+
138
+
**Note:** Check the existing [issues](https://github.com/magento/devdocs/issues) on GitHub to see if someone has already reported the issue.
108
139
109
-
**Note:** Check the [existing issues](https://github.com/magento/devdocs/issues) on GitHub to see if someone has already reported the issue.
140
+
You can provide feedback using the following options:
110
141
111
-
You have a couple of options to enter an issue:
112
142
- Have general feedback? Create an issue on [GitHub DevDocs](https://github.com/magento/devdocs/issues/new/choose).
113
143
- Have feedback on a specific DevDocs page? Click the **Give us feedback** link at the top right of the page to report on the currently open topic.
In general, the same [guidelines](https://devdocs.magento.com/guides/v2.3/contributor-guide/maintainers.html) for [`magento/magento2`](https://github.com/magento/magento2) maintainers apply to devdocs maintainers. However, there are some additional guidelines specific to devdocs that will help you as a maintainer.
- Enforce the use of the issue/pull requests template
10
+
- Ask contributors to link to the code base to validate documentation updates when applicable
11
+
- Ask contributors not to contribute to v2.0 docs
12
+
- If a maintainer creates a pull request, it should be reviewed by another maintainer or DevDocs staff member
13
+
14
+
## Labels
15
+
16
+
Labels are important because they help us identify pull requests and ensure that contributors receive points and recognition. See [devdocs awards and points](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#devdocs-awards-and-points).
17
+
18
+
Here is a brief summary of the most important labels:
19
+
20
+
-`New Topic`: Entirely new documents
21
+
-`Major Update`: Significant new info: new section in existing topic, etc.
22
+
-`Technical`: Changes to technical content/code/processes/naming conventions (any change to technical content)
23
+
-`Editorial`: Typos, grammatical inconsistencies, or minor rewrites
24
+
-`small changes`: See [Small changes workflow](#small-changes-workflow)
25
+
26
+
We also use version labels when appropriate.
27
+
28
+
As a maintainer, we expect you to add or remove labels when appropriate.
29
+
30
+
See https://github.com/magento/devdocs/labels for all labels and their descriptions.
31
+
32
+
## Testing
33
+
34
+
Currently, we only test internal links. In the future, we plan to expand tests to include external links, markdown linting, and spell checking.
35
+
36
+
We use private CI/CD stack and do not provide access to it.
37
+
38
+
Every pull request to the `master` branch must pass tests before it can be merged. When a pull request is ready for tests, a member of the [`devdocs-admins`](https://github.com/orgs/magento/teams/devdocs-admins) team must add the test trigger phrase to the pull request as a comment. The trigger phrase is "_running tests_". By approving a pull request, you are signalling an admin that the pull request is ready for tests.
39
+
40
+
## Projects
41
+
42
+
We use several projects to help organize issues and pull requests. You can add existing issues and pull requests to these projects as you see fit.
We prefer Markdown over HTML (in most cases). You can use [kramdown](https://kramdown.gettalong.org/syntax.html) syntax for more markup features and [Liquid](https://jekyllrb.com/docs/liquid/) for in-topic scripting.
49
+
50
+
## Small changes workflow
51
+
52
+
Before merging a pull request to the `master` branch, it must pass automated testing. Testing takes about 30 minutes to complete for each pull request, so we created a workflow to save time for small changes.
53
+
54
+
-**Individual pull requests to `master`**—15 individual pull requests to `master` x 30 minutes per pull request = 7.5 hrs of testing time
55
+
-**Multiple pull requests using `small_changes`**—1 `small_changes` pull request (containing 15 individual pull requests) to `master` x 30 minutes = 30 minutes of testing time
56
+
57
+
This workflow is for typos, formatting issues, and minor text additions or deletions. It is not for substantial new content, changes to tables, new files, or files that have been moved.
58
+
59
+
Periodically, we will create a pull request from `small_changes` to `master` and then run tests on that pull request to save time.
60
+
61
+
### Process
62
+
63
+
1. Review the pull request and either approve it or request changes.
64
+
1. Apply the `Small changes` label if one of the following labels should also be applied:
65
+
66
+
-`Editorial`
67
+
-`Technical`
68
+
69
+
1. That's it! A devdocs-admin will run tests and merge.
0 commit comments