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: src/contributor-guide/maintainer-handbook.md
+43-37Lines changed: 43 additions & 37 deletions
Original file line number
Diff line number
Diff line change
@@ -3,101 +3,107 @@ group: contributor-guide
3
3
title: Maintainer's Handbook
4
4
---
5
5
6
-
This document aims to describe the activities performed by a Community Maintainer, provide some insights and description on the tools integrated with our GitHub that helps our Maintainers during their journey.
6
+
This document describes activities performed by a community maintainer, provides some insight and description of the tools integrated within GitHub to assist our maintainers.
7
7
8
-
### Magento Repositories and Projects
8
+
### Magento repositories and projects
9
9
10
-
Within our GitHub organization there are many repositories that our Maintainers can interact with, the repository that has most activity is the [magento2](https://github.com/magento/magento2), but depending on your interest you may also interact with some of our other repositories, like:
10
+
Within our GitHub organization there are numerous repositories that our maintainers interact with. The repository that has most activity is [magento2](https://github.com/magento/magento2). Depending on your interest, you might also interact with some of our other repositories, such as:
Because most of our contributions are to [magento2](https://github.com/magento/magento2) repository, we have created several GitHub projects to help us to manage these contributions.
18
+
Because most contributions go to the [magento2](https://github.com/magento/magento2) repository, there are several GitHub projects to help manage these contributions.
19
19
20
20
21
21
22
-
Each project has its own description that will help you to understand their responsibility, one important project that we focus most of our attention is the **High Priority Pull Request Dashboard**, where you can find the Pull Requests that will bring most value for the community and will be delivered first.
22
+
Each project has a description of what it does. One important project is the **High Priority pull request Dashboard**, where you can find the pull requests (PR) that will bring most value for the community and will be delivered first.
23
23
24
-
### Pull Request Dashboard
24
+
### Pull request dashboard
25
25
26
-
Within your projects we have the Pull Request Dashboards, there you will find our Kanban board which has several columns that represents our Pull Request delivery workflow. The columns title are self-explained and should represent the action required for the Pull Requests on that column.
26
+
Within projects there are pull request dashboards. There you will find our Kanban board, which has columns representing the PR delivery workflow. The columns title are self-explanatory and should represent the action required for the pull requests on that column.
The first step towards the review process is to pick and self-assign one Pull Request from our dashboard. To help Maintainers to choose a Pull Request to be reviewed we have several labels, the most important one is the **Priority** label and, we encourage our Maintainers to choose the Pull Requests with the highest priority from the **High Priority Pull Request Dashboard**on the **Pending Review** column.
32
+
The first step in the review process is to choose and self-assign a pull request from the dashboard. To help maintainers choose a PR to review, there are several labels, the most important being **Priority**. We encourage our maintainers to choose pull requests with the highest priority from the **High Priority pull request Dashboard**in the **Pending Review** column.
33
33
34
-
Once you have chosen the Pull Request, there are some steps to be followed during the review process.
34
+
Once you have chosen a pull request, there are some steps to be followed during the review process.
35
35
36
-
#### Check CLA and Builds
36
+
#### Check CLA and builds
37
37
38
-
The first thing we encourage our Maintainer to check is if the Contributor has signed the Adobe CLA, without this signature we cannot accept the contribution. If the Contributor has not signed the CLA yet, that specific check will be red and, we should add a comment to the Pull Request requesting the Contributor to sign the CLA.
38
+
The first thing we encourage a maintainer to check is if the contributor has signed the Adobe CLA. Without this signature, we cannot accept the contribution. If the Contributor has not signed the CLA, that check will be red. Add a comment to the pull request requesting the contributor to sign the CLA.
39
39
40
-
Once the CLA is signed, we can check the other builds, those builds are run based on Contributors Pull Request and will highlight if the proposed changes are causing some existing functionality to break or aren’t fully compliant with our requirements. In case Magento Heath Index or Semantic Version Checker fails, the approach should either be changed or the proposed changes has to be approved by the internal team through the approval process. More information can be found on our [Contributor Guide]({{ site.baseurl }}/contributor-guide/pull-request-tests.html).
40
+
Once the CLA has been signed, we can check the other builds. Those builds are run based on the contributors pull request and will let us know if the proposed changes are causing existing functionality to break or are not fully compliant with coding standards. If either the Magento Heath Index or Semantic Version Checker fail, the PR should be changed or the proposed changes will need approval by the Magento team. More information can be found on our [Contributor Guide]({{ site.baseurl }}/contributor-guide/pull-request-tests.html).
41
41
42
42
43
43
44
-
#### Check Pull Request Target
44
+
#### Check the pull request target
45
45
46
-
It is important to make sure the pull request is being targeted to the right branch, for example, if the Contributor’s Pull Request does not bring backwards incompatible changes, these changes should be targeted at the current minor release branch, if the Contributor’s Pull Request brings backwards incompatible changes or it is part of a separate project, it may need to be target to a different branch.
46
+
It is important to check the pull request is targeted to the correct branch. For example, if the contributor’s PR does not create backwards incompatible changes, these changes should be targeted at the current minor release branch. If the PR introduces backwards incompatible changes, or it is part of a different project, it must target the correct branch.
The code review is one of the most important part of the review process, our Community Maintainers are responsible to review the proposed changes and evaluate if they are following the [Magento Technical Guidelines]({{ site.baseurl }}/guides/v2.4/coding-standards/technical-guidelines.html). It is also important to evaluate if the proposed changes are backward compatible and follow the rules and best practice of our [Backward Compatible Development Guide]({{ site.baseurl }}/contributor-guide/backward-compatible-development/), we also trust our Maintainers judgement for other recommendations to increase contribution quality.
52
+
The code review is one of the most important parts of the review process. Our community maintainers are responsible for reviewing the proposed changes and confirm they are following the [Magento Technical Guidelines]({{ site.baseurl }}/guides/v2.4/coding-standards/technical-guidelines.html). It is important to evaluate if the proposed changes are backward compatible and follow the rules and best practice of our [Backward Compatible Development Guide]({{ site.baseurl }}/contributor-guide/backward-compatible-development/). We count on our Maintainers judgement for other recommendations to increase contribution quality.
As described on our [Definition of Done]({{ site.baseurl }}/contributor-guide/contributing_dod.html), all the code changes must be covered by automated tests, it is also part of the review process to guarantee the changes are covered, make sure the type of test used to cover the changes is the most adequate and add the appropriate label to the Pull Request. If the Pull Request is not covered with tests, we recommend the Maintainer to communicate and advice the Contributor on how to add test coverage to the changes.
58
+
As described on our [Definition of Done]({{ site.baseurl }}/contributor-guide/contributing_dod.html), all code changes must be covered by automated tests. It is part of the review process to:
59
+
60
+
- Guarantee the changes are properly covered
61
+
- Ensure the type of test used to cover the changes is appropriate
62
+
- Add the appropriate label to the pull request
63
+
64
+
If the pull request is not covered by tests, the maintainer should advise the contributor on how to add proper test coverage.
Once all the steps above are done the Maintainer can approve the Contributor’s Pull Request. After approving the Pull Request, it will proceed through our delivery process and will be tested to guarantee it’s quality.
70
+
Once all the steps above are complete, the maintainer can approve the contributor’s PR. After approving the PR, it will proceed through the delivery process and will be tested to guarantee quality.
We are thankful for all contributions, and we always recognize our most active members. Contributors can earn points in numerous ways with a focus on Pull Requests to the backlog and special projects. We have a set of labels that highlight different types of achievements, we encourage our Maintainers to review all the [existing awards]({{ site.baseurl }}/contributor-guide/contributing.html#points) and based on the information provided decide which award is most suitable.
76
+
We are thankful for all contributions, and we recognize our most active members. Contributors earn points in numerous ways with a focus on PRs in the backlog and special projects. We use labels to highlight the different types of achievements. We encourage maintainers to review all the [existing awards]({{ site.baseurl }}/contributor-guide/contributing.html#points) and based on the information provided decide which award is most suitable.
71
77
72
78
73
79
74
80
### Other useful information
75
81
76
-
Besides, the repositories, projects and code review process, there are more information, tools and processes that are important for our Maintainers to know about.
82
+
Besides the repositories, projects and code review process, there are other tools and processes that maintainers should know about.
77
83
78
-
#### Related Pull Requests
84
+
#### Related pull requests
79
85
80
-
Magento is a complex platform and, some changes may require changes on multiple repositories. For example, if a Contributor’s Pull Request performs a change on a feature that is being used on Magento Commerce edition, it may be required to create a Pull Request on a separate repository.
86
+
Magento is a complex platform and, some changes may require changes in multiple repositories. For example, if a contributor’s PR performs a change on a feature that is being used on Magento Commerce edition, it may require a parallel PR in that repository.
81
87
82
-
If that is the case, our builds need to run using the changes from both Pull Requests, to do so we must use the Related Pull Requests feature, this feature can be used by adding the link to the related Pull Request on the main Pull Request description, more details on this is available on our[Contributor Guide]({{ site.baseurl }}/contributor-guide/pull-request-tests.html#related-pull-requests).
88
+
In that case, builds need to run using the changes from both PRs. To do so, use the 'related pull requests' feature. This feature is enabled by adding the link to the related pull request on the main pull request description using Github keywords. Details on this are in the[Contributor Guide]({{ site.baseurl }}/contributor-guide/pull-request-tests.html#related-pull-requests).
The deployment tool assists Contributors and Maintainers to test their changes or validate if an issue exists on clean Magento installation. More information on deployment tool can be found [here]({{ site.baseurl }}/contributor-guide/contributing.html#contributor-assist).
94
+
The deployment tool helps contributors and maintainers to test changes or validate if an issue exists on clean Magento installation. More information on the deployment tool can be found in the [Contributor's Guide]({{ site.baseurl }}/contributor-guide/contributing.html#contributor-assist).
We gather our Community Maintainers on our Slack channel, once you are on-boarded as a Maintainer we will add you to this channel and, you will be able to discuss questions related to contributions and share your ideas or information with other Maintainers.
100
+
We communicate with our community maintainers on our Slack channel. Once you are on-boarded as a maintainer, we will add you to this channel. You can discuss contributions and share your ideas or information with other maintainers.
0 commit comments