GitHub provides many features such as organizations and teams to help organize projects. MDN works on open source projects with outside collaborators, so we don't require many of the features needed by enterprise clients.
Here's how we use the roles provided by GitHub:
Repositories are where the work gets done. GitHub splits repository permissions into read, write, and admin permissions. Read permissions are only important for private repositories, which are not used in the MDN organization. Admin permissions are usually restricted to organization members (see below). This policy is mostly concerned with write permissions, which gives users the ability to merge pull requests and manage projects.
The repositories can be categorized by their impact:
- Tier 1: Code in this repo runs on Mozilla servers, on https://developer.mozilla.org, or on another mozilla.org domain. Changes need to be reviewed for security. Examples include Kuma, KumaScript, and samples-server.
- Tier 2: Code and data in this repo appear on MDN Web Docs, but are served from a non-mozilla.org domain. Changes need to be reviewed to ensure they meet MDN standards. Examples include browser-compat-data, interactive-examples, and webaudio-examples.
- Tier 3: Code and data in this repo do not appear on MDN Web Docs. Changes need to be reviewed to meet the standards of the repository maintainer(s). Examples include pab and wp-promote-mdn.
Repository members with write permissions have the ability to review and merge pull requests, and in some cases can deploy to production. This means that Tier 1 membership has the same requirements as for organization roles (see below). A Tier 1 project should have at least 3 members, including at least one with admin permissions.
For Tier 2 projects, only organizational members should have admin permissions. The organizational members can invite others to help manage the project as outside collaborators with write permissions. A Tier 2 project should have at least 2 members, including at least one with admin permissions.
For Tier 3 projects, an outside collaborator can get administration permissions. A Tier 3 project needs 1 admin.
Projects with no members should be archived or deleted by an organization owner.
All members should:
- Agree to abide by our Code of conduct.
- Use Two factor authentication for their GitHub account.
| Tier 1 | Tier 2 | Tier 3 | Responsibility |
|---|---|---|---|
| ✓ | ✓ | ✓ | Ensure the repository meets the minimum requirements, such as having a LICENSE and README.md files. |
| ✓ | ✓ | ✓ | At least one member should respond to an issue or pull request within one week. |
| ✓ | ✓ | Use pull requests for most changes, rather than pushing directly to the master branch, to facilitate discussion on GitHub. | |
| ✓ | ✓ | Ensure that pull requests will not break MDN Web Docs, using automated and manual checks as appropriate, before merging. | |
| ✓ | ✓ | Repository admins can decide pull request policy (are reviews required, who can review, etc.). This policy should be documented. | |
| ✓ | Review pull requests for security impact before merging. | ||
| ✓ | A positive review is needed to merge a pull request, so that two people have seen the code before it goes into production. |
Owners and Members at the Organization level are granted permissions across all repositories.
There should be three to five owners. With less than three, there is a high risk that owner-level actions will be delayed. With more than five, there is high risk that there will be Owners that never need their increased access, and don't take the role seriously.
Organization Owners and Members have wide permissions to manage users, teams, and repositories, and to see details about the organization. Because of this we require that Organization Owners and Members are:
- Current Mozilla staff and core contributors.
- For current staff, be assigned to MDN, a related project, or a supporting team.
- For core contributors, have a vouched Mozillians profile in the nda group.
- Have Two-Factor Authentication enabled for their account.
We encourage organization-level members to publicize their membership on GitHub.
Members should:
- Follow and enforce MDN team norms, including the code of conduct and Mozilla Policies.
- Follow and contribute to issues and discussions on this mdn meta repo. An issue should get feedback from one or more members within one week.
- Follow MDN organization policies described in this repo, to show a good example and to ensure they are not overly burdensome.
- Suggest, document, and implement new policies through the pull request process.
- Add collaborators to repositories -- or remove them -- as needed.
- Archive or delete unmaintained projects.
- Discuss GitHub features, decide which to use, and document decisions in this repository.
In addition, Owners should:
- Add and remove organization owners and members as needed
- Add repositories (as fresh projects or transfers) as needed
GitHub's Teams feature has evolved as GitHub adds project management features. The MDN team experimented with teams in the past, but they are currently under-used.
Our current teams currently give wide permissions to repositories, making it unclear who is responsible for maintaining a given repository. We should assign repository members as collaborators, and see if this eliminates our need for teams. If we decide to use teams, they should be marked as Public, not Private, and the team policy documented here. If we don't use teams, we should remove them.