diff --git a/files/en-us/mdn/community/contributing/getting_started/index.md b/files/en-us/mdn/community/contributing/getting_started/index.md new file mode 100644 index 000000000000000..4030f4413c8b775 --- /dev/null +++ b/files/en-us/mdn/community/contributing/getting_started/index.md @@ -0,0 +1,53 @@ +--- +title: Getting started with MDN Web Docs +slug: MDN/Community/Contributing/Getting_started +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +We are an open community of developers, technical writers, and learners building resources for a better Web, regardless of brand, browser, or platform. Anyone can contribute, and each person who does contribute makes us stronger. Together we can continue to drive innovation on the Web to serve the greater good. It starts here, with you. + +[Join us!](https://github.com/mdn/mdn-community/) + +## What can I do to help? + +There are multiple avenues you can take to contribute to MDN, depending on your skill set and interests. Therefore, along with each task, we provide a short description and an approximate time each type of task typically takes. + +> If unsure what to do, you are always welcome to [ask for help](https://github.com/mdn/mdn-community/). +> Also note that our small, but mighty docs team maintains this repo, to preserve our bandwidth, off topic conversations will be closed. + +## Primary contribution types + +We have created a [contributors task board](https://github.com/orgs/mdn/projects/25/views/1) to help you find contribution opportunities that will meaningfully impact the project. The board has an overview and separate views for specific contribution types. + +### Getting ready to contribute + +To contribute, you will need a GitHub account. If you do not already have one, go ahead and [sign up](https://github.com/signup) for an account before continuing. If you are new to GitHub, we encourage you to take the following free, self-paced courses and reading material offered by GitHub. With this knowledge, you can focus on your contributions and not learn a new tool at the same time. + +> NOTE: Do not feel overwhelmed or like you have to read through and complete _all_ of the course work. With the knowledge gained from the "Introduction to GitHub" course, you will be well on your way. + +- [Introduction to GitHub](https://github.com/skills/introduction-to-github) +- [Setting up Git](https://docs.github.com/en/get-started/quickstart/set-up-git) +- [GitHub workflow](https://docs.github.com/en/get-started/quickstart/github-flow) +- [Using Markdown](https://github.com/skills/communicate-using-markdown) + +### Additional reading and learning material + +- [Basic etiquette for open source projects](../../open-source-etiquette/index.md): If you've never contributed to an open source project before, we encourage you to read this document. +- [Learn web development](https://developer.mozilla.org/docs/Learn): If you are new to HTML, CSS, JavaScript, we have some great content to help you get started. +- [Deep dive into collaborating with pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests) + +Some writing-specific contribution opportunities will require a reasonable understanding of the English language. That said, do not let perfect be the enemy of “good enough.” Even if your grammar isn’t good, don’t worry about it! We have a team of people who aim to ensure that MDN’s contents are as good as possible. In addition, someone will be along to ensure your work is tidy and well-written. + +Once you’ve decided what kind of task you want to work on, it is time to head over to the [contributors task board](https://github.com/orgs/mdn/projects/25/views/1), pick an issue, and let us know by commenting on the issue and tagging the `@mdn/mdn-community-engagement` team. Someone from the team will respond and assign the issue to you. + +This ensures that two people do not work on the same issue, and you will know who to contact should you get stuck. + +### Contributions + +When contributing, you agree to make your contributions available under the [Attribution-ShareAlike license](https://creativecommons.org/licenses/by-sa/4.0/) (or an alternative license already specified by the page you are editing). In addition, code samples are available under [Creative Commons CC-0](https://creativecommons.org/share-your-work/public-domain/cc0/) (a Public Domain dedication). + +> If you have any questions or concerns about anything discussed here, please [open a discussion](https://github.com/mdn/mdn-community/discussions/categories/content) and let us know. diff --git a/files/en-us/mdn/community/contributing/index.md b/files/en-us/mdn/community/contributing/index.md new file mode 100644 index 000000000000000..12e49ba8ca15fb4 --- /dev/null +++ b/files/en-us/mdn/community/contributing/index.md @@ -0,0 +1,14 @@ +--- +title: Contributing to MDN Web Docs +slug: MDN/Community/Contributing +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +- [Getting started](getting-started/index.md) +- [Our repositories](our-repositories/index.md) +- [Translated content](translated-content/index.md) +- [Security vulnerability response](security-vulnerability-response/index.md) diff --git a/files/en-us/mdn/community/contributing/our_repositories/index.md b/files/en-us/mdn/community/contributing/our_repositories/index.md new file mode 100644 index 000000000000000..c061ac18981b4a1 --- /dev/null +++ b/files/en-us/mdn/community/contributing/our_repositories/index.md @@ -0,0 +1,84 @@ +--- +title: MDN Web Docs Repositories +slug: MDN/Community/Contributing/Our_repositories +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +[MDN Web Docs](https://developer.mozilla.org) is a complex project with lots of moving parts. It's a good idea to get familiar with the projects different repositories. This document intends to help you find the different repositories (repos) you may need when contributing to different parts of the MDN Web Docs project. + +## Repository tiers + +### Tier 1 + +Code in these repositories are core to the MDN Web Docs project and runs on https://developer.mozilla.org, or another Mozilla owned domain. + +- [mdn/content](https://github.com/mdn/content) +- [Yari](https://github.com/mdn/yari) +- [rumba](https://github.com/mdn/rumba) +- [browser-compat-data](https://github.com/mdn/browser-compat-data) +- [interactive-examples](https://github.com/mdn/interactive-examples) +- [bob](https://github.com/mdn/bob) + +A Tier 1 project should have at least 3 members, including at least two with admin permissions. + +### Tier 2 + +These repositories are mainly concentrated on supporting content such as code examples, the MDN Web Docs learn area, localisation, and examples projects. Examples include: + +- [dom-examples](https://github.com/mdn/dom-examples) +- [translated-content](https://github.com/mdn/translated-content) +- [learning-area](https://github.com/mdn/learning-area) + +A Tier 2 project should have at least 2 members, including at least one with admin permissions. + +### Tier 3 + +These are repository used for project planning, documenting the project itself, and community engagement. Examples include: + +- [mdn-community](https://github.com/mdn/mdn-community) +- [mdn/mdn](https://github.com/mdn/mdn) +- [content-team-projects](https://github.com/mdn/content-team-projects). + +A Tier 3 project needs 1 admin. + +## Core repos + +- **Core content**: . The most important repo for MDN Web Docs content — this is where all the core English content of the site is stored, and where you'll make all standard changes to page content. +- **MDN Web Docs Platform**: . This is where the MDN Web Docs platform is stored, and where you'll go if you want to make changes to our high level page structure or rendering machinery. +- **Browser compatibility data**: . This is where the data used to generate the browser compatibility tables found on our reference pages is stored ([example](/en-US/docs/Web/HTML/Element/progress#browser_compatibility)). If you have information about browser compatibility of Web features — or are willing and able to do some research and/or experimentation — you can help update MDN's [Browser Compatibility Data](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md) +- **Interactive examples**: . This repo stores the example code blocks that are found at the top of many of our reference pages ([example](/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis)). Edit those examples here. +- **Bob** aka Builder of Bits: + This repo stores the rendering code that produce the nice editable, copyable examples found at the top of many of our reference pages ([example](/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis)). +- **Translated content**: . This is where localized content lives. Go here if you want to help translate pages into any of our [actively maintained locales](https://github.com/mdn/translated-content#locales). +- **Workflows**: + A growing collection of reusable GitHub Actions for use on MDN Web Docs repositories. + +## Code example + +### Code examples and demos + +[//]: # "TODO: UPDATE WITH REPO TRIAGE" + +The MDN Web Docs GitHub org contains a huge number of example repos. These generally contain free-standing code examples that are often linked to from our pages, but occasionally you’ll find one of these examples embedded into a page using a macro call like this — `{{EmbedGHLiveSample("css-examples/learn/tasks/grid/grid1.html", '100%', 700)}}`. + +Always remember, if you are updating the code on any given page, you'll need to update the corresponding example repo as well. + +- [**dom-examples**](https://github.com/mdn/dom-examples) +- [**css-examples**](https://github.com/mdn/css-examples) +- [**webaudio-examples**](https://github.com/mdn/webaudio-examples) +- [**webassembly-examples**](https://github.com/mdn/webassembly-examples) +- [**indexeddb-examples**](https://github.com/mdn/indexeddb-examples) +- [**js-examples**](https://github.com/mdn/js-examples) +- [**html-examples**](https://github.com/mdn/html-examples) +- [**web-components-examples**](https://github.com/mdn/web-components-examples) +- [**webextension-examples**](https://github.com/mdn/webextensions-examples) +- [**webgl-examples**](https://github.com/mdn/webgl-examples) +- [**pwa-examples**](https://github.com/mdn/pwa-examples) +- [**houdini-examples**](https://github.com/mdn/houdini-examples) +- [**headless-examples**](https://github.com/mdn/headless-examples) +- [**perf-examples**](https://github.com/mdn/perf-examples) +- [**devtools-examples**](https://github.com/mdn/devtools-examples) diff --git a/files/en-us/mdn/community/contributing/security_vulnerability_response/index.md b/files/en-us/mdn/community/contributing/security_vulnerability_response/index.md new file mode 100644 index 000000000000000..aec1ab121a9d5e9 --- /dev/null +++ b/files/en-us/mdn/community/contributing/security_vulnerability_response/index.md @@ -0,0 +1,41 @@ +--- +title: Security Vulnerability Response Steps +slug: MDN/Community/Contributing/Security_vulnerability_response +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +## A little history + +On ~27 November 2018 an NPM security vulnerability was announced for all users that depend, either directly or indirectly, on the [event-stream](https://snyk.io/blog/malicious-code-found-in-npm-package-event-stream) package. It was a very targeted attack, that only activated if the Copay bitcoin wallet was installed, whereupon it tried to steal the contents. + +Two of our projects, namely [interactive-examples](https://github.com/mdn/interactive-examples/) and [BoB](https://github.com/mdn/bob/), depend on an NPM package called [npm-run-all](https://www.npmjs.com/package/npm-run-all), which in turn depended on the event-stream package. + +This meant that not only was staff at risk, but people who have forked either of these repositories might have been affected as well. Thankfully the maintainers of the affected package reacted swiftly and released an update to address the issue. Because we have the [Renovate bot](https://github.com/marketplace/renovate) running against these repositories, there was a [pull request](https://github.com/mdn/interactive-examples/pull/1239/) ready to merge. + +This only resolved one part of the problem though. Our users still needed to be notified. + +## Steps taken + +The community for especially the interactive-examples project was rather large, and not everyone active, but we still needed a way to reach out to everyone. The first step was then to open an issue against each of the repositories detailing the problem: + +- [interactive-examples](https://github.com/mdn/interactive-examples/issues/1242) +- [bob](https://github.com/mdn/bob/issues/184) + +That by itself is not enough as users do not necessarily actively monitor issues. We therefore, needed to look at all of the forks of the project, for example: https://github.com/mdn/interactive-examples/network/members + +We then copied all of the usernames for these users and pinged them on the above issue, for example: https://github.com/mdn/interactive-examples/issues/1242#issuecomment-442110598 + +This was very effective from the response we received in the issue, but we could not leave it there. The next step was to post a comment on each of the open pull requests informing the user of the problem, and what their next steps should be: +https://github.com/mdn/interactive-examples/pull/1144 + +With this, we felt rather confident that between us reaching out, and coverage of the issue online by NPM and other channels, would ensure that we ensured our users are safe. + +As a final step, @schalkneethling posted a message on Twitter which was in turn retweeted by the [MDN Web Docs Twitter account](https://twitter.com/schalkneethling/status/1067436637385179136). + +### In closing + +Hopefully, these types of incidents will be few and far between. Should this happen again however, the above provides a solid guideline on how to respond. diff --git a/files/en-us/mdn/community/contributing/translated_content/index.md b/files/en-us/mdn/community/contributing/translated_content/index.md new file mode 100644 index 000000000000000..abf2d17cc359d8d --- /dev/null +++ b/files/en-us/mdn/community/contributing/translated_content/index.md @@ -0,0 +1,60 @@ +--- +title: MDN Web Docs Localisation +slug: MDN/Community/Contributing/Translated_content +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +Since December 14th 2020, MDN has been running on the new GitHub-based [Yari platform](https://github.com/mdn/yari). This has a lot of advantages for MDN, but we've needed to make radical changes to the way in which we handle localization. This is because we've ended up with a lot of unmaintained and out-of-date content in our non-en-US locales, and we want to manage it better in the future. + +We have frozen all localized content (meaning that we won't accept any edits to it; it'll be read-only), EXCEPT for the below locales — these locales have dedicated teams taking responsibility for maintaining them. + +## Active locales + +> **Note:** If you want to contribute to one of the existing active locales get in touch with one of the active members listed below, or [contact us for help](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help). + +### Brazilian Portuguese (pt-BR) + +- Discussions: [Telegram (MDN localization in Brazilian Portuguese)](https://t.me/mdn_l10n_pt_br) +- Current contributors: [Luisa Migueres](https://github.com/lumigueres), [Julio Sampaio](https://github.com/juliosampaio), [Josiel Rocha](https://github.com/josielrocha), [Clóvis Lima Júnior](https://github.com/clovislima) + +### Chinese (zh-CN, zh-TW) + +- Discussions: [Telegram (MozTW L10n channel)](https://moztw.org/community/telegram/) +- Current contributors: [Irvin](https://github.com/irvin), [t7yang](https://github.com/t7yang), [dibery](https://github.com/dibery) + +### French (fr) + +- Discussions : [Matrix (#l10n-fr channel)](https://chat.mozilla.org/#/room/#l10n-fr:mozilla.org) +- Current contributors: [cw118](https://github.com/cw118), [Jb Audras](https://github.com/audrasjb), [SphinxKnight](https://github.com/SphinxKnight), [tristantheb](https://github.com/tristantheb) + +### Japanese (ja) + +- Discussions: [Slack (#translation channel)](https://mozillajp.slack.com/), [GitHub (mozilla-japan)](https://github.com/mozilla-japan/translation), [Google Group (Mozilla.translations.ja)](https://groups.google.com/forum/#!forum/mozilla-translations-ja) +- Current contributors: [mfuji09](https://github.com/mfuji09), [hmatrjp](https://github.com/hmatrjp), [potappo](https://github.com/potappo), [dynamis](https://github.com/dynamis), [kenji-yamasaki](https://github.com/kenji-yamasaki) + +### Korea (ko) + +- Discussions: [Kakao Talk (#MDN Korea)](https://open.kakao.com/o/gdfG288c) +- Current contributors: [hochan222](https://github.com/hochan222), [yechoi42](https://github.com/yechoi42), [cos18](https://github.com/cos18), [GwangYeol-Im](https://github.com/GwangYeol-Im), [pje1740](https://github.com/pje1740), [nKiNk](https://github.com/nKiNk), [yujo11](https://github.com/yujo11) + +### Russian (ru) + +- Discussions: [Matrix (#mdn-l10n-ru channel)](https://chat.mozilla.org/#/room/#mdn-l10n-ru:mozilla.org) +- Current contributors: [armanpwnz](https://github.com/armanpwnz), [captainspring](https://github.com/captainspring), [mpstv](https://github.com/mpstv), [myshov](https://github.com/myshov), [Saionaro](https://github.com/Saionaro), [sashasushko](https://github.com/sashasushko), [lex111](https://github.com/lex111) + +### Spanish (es) + +- Discussions: [Matrix (#mdn-l10n-es channel)](https://chat.mozilla.org/#/room/#mdn-l10n-es:mozilla.org) +- Current maintainers: [@JuanVqz](https://github.com/JuanVqz), [@dacalderonp](https://github.com/dacalderonp), [@lasr21](https://github.com/lasr21), [@tuxxy](https://github.com/tuxxy) + +> **Note:** If you want to discuss unfreezing a currently frozen locale, the [guidelines on what is required can be found here](https://github.com/mdn/translated-content/blob/main/PEERS_GUIDELINES.md#activating-a-locale). + +## See also + +- [MDN localization update, February 2021](https://hacks.mozilla.org/2021/02/mdn-localization-update-february-2021/) — the latest state of localization on MDN +- [An update on MDN Web Docs' localization strategy](https://hacks.mozilla.org/2020/12/an-update-on-mdn-web-docs-localization-strategy/) — updated strategy based on community feedback +- [MDN Web Docs evolves! Lowdown on the upcoming new platform](https://hacks.mozilla.org/2020/10/mdn-web-docs-evolves-lowdown-on-the-upcoming-new-platform/) — more on the advantages of the new platform, and the rationale behind the localization changes. diff --git a/files/en-us/mdn/community/discussions/index.md b/files/en-us/mdn/community/discussions/index.md new file mode 100644 index 000000000000000..f9bf9ba711f24b8 --- /dev/null +++ b/files/en-us/mdn/community/discussions/index.md @@ -0,0 +1,211 @@ +--- +title: MDN Web Docs Community Discussions +slug: MDN/Community/Discussions +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +On MDN Web Docs, we encourage our community to start and/or engage in discussions around topics related to the overall project. Discussions are categorized by different topic areas. We ask that you keep each discussion focused on the topic at hand instead of covering multiple topics in one discussion. + +_NOTE:_ mdn-community/discussions is not the place to report problems. For any problems you encounter on MDN Web Docs, it is best to raise issues against the [relevant project](https://github.com/mdn/). If you're ever in doubt about whether to open an issue or a discussion, consider the following guidelines: + +- Issues are for reporting a bug or a work item with clearly defined and actionable tasks and outcomes. +- Discussions are the right place if the issue needs a discussion to agree upon a course of action or define an actionable piece of work. + +Check out the definition of each discussion category below so that you can start your discussion in the proper place. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Discussion CategoryDiscussion Subject
+ 📣 + Announcements + + This category is reserved for MDN Web Docs staff. While there is nothing + in place to prevent others from posting here, we ask that you choose one + of the other available categories. +
+ 🔮 + Browser compatibility data + + Discussions related to the + browser-compat-data + project. +
+ ✏️ + Content + + Discussions related to the + content on MDN Web Docs. + Note: This is not the place to ask for help with code examples. + For code-related help, please + join our community on Discourse. +
+ 🙋 + Content suggestions + + Discussions related to ideas for new content or improvements to existing + content on MDN Web Docs. You can propose your ideas here along with a + description of how the change will be useful to our readers and/or links + to relevant resources. We commonly label these as opportunity + assessments. +
+ 🎨 + Design system + + Discussions related to design improvements. Design is subjective, but we + are always open to suggestions from the community. Any improvement that + can help the MDN Web Docs experience even better for a wider audience is + welcome. If you have constructive feedback around the design, user + experience, and accessibility of MDN Web Docs, we'd love to hear from + you. +
+ 👩‍💻 + Code examples + + Discussions related to all code examples on MDN Web Docs. This includes + interactive examples, live samples and static code examples. For help + with general coding challenges on MDN Web Docs, please + join our community on Discourse. +
+ 🌐 + Translated content + + Discussions related to the + translated-content + repository covering our + supported locales. This is also typically where + announcements of macro deprecation + will happen. +
+ 👾 + MDN Plus + + Discussions related to the existing + MDN Plus feature set + as well as feature ideas. For MDN Plus support such as subscriptions, + please refer to our + official support channel. +
+ 🛠️ + Platform + + Discussions related to the + core MDN Web Docs platform. + Your suggestions to improve the architecture and existing features, such + as navigation and search, are welcome. However, if you believe you found + a bug related to the platform, please + report it + on the Yari repository. This is also the place for discussions related + to existing tooling, such as + BoB, + markdown, + reusable workflows, etc. + NOTE: This category is not for MDN Plus-related feature discussions. + There is a separate discussion category for MDN Plus. +
+ 🤖 + Polls + + This category is meant for use by the MDN Web Docs staff. We will use + this category to run polls around topics where we need your input. So, + keep your eyes peeled. 👀 +
diff --git a/files/en-us/mdn/community/index.md b/files/en-us/mdn/community/index.md new file mode 100644 index 000000000000000..3134b356fbb34ef --- /dev/null +++ b/files/en-us/mdn/community/index.md @@ -0,0 +1,50 @@ +--- +title: MDN Web Docs Community Guidelines +slug: MDN/Community +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +👋 Welcome to MDN Web Docs on GitHub! MDN Web Docs is an open-source, collaborative project that documents web platform technologies, including [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML), [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), and [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API). We also provide extensive [learning resources](https://developer.mozilla.org/en-US/docs/Learn) for early-stage developers and students. + +## Ways to contribute + +[//]: # "TODO: Remember to update these links as we move the documentation around." + +- [Fixing known high impact issues](https://github.com/orgs/mdn/projects/25/views/1) +- [Reviewing pull requests](pull-requests/) +- [Help beginners to learn on MDN Web Docs](learn-forum/) +- [Contribute to MDN Web Docs interactive examples](https://github.com/mdn/interactive-examples/blob/main/CONTRIBUTING.md) +- [Help translate MDN Web Docs](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Localize) +- [Help fix known platform issues](https://github.com/mdn/yari/issues) +- [Help us keep browser compatibility data up to date.](https://github.com/mdn/browser-compat-data) + +## Quick Links + +- [Our repositories overview](contributing/our-repositories/) +- [Users and teams](users-teams/) +- [If you are familiar with Git and GitHub](./contributing/getting-started/general/index.md) +- [Get Started with Git and GitHub](./contributing/getting-started/beginners/index.md) + +## Code of conduct + +By participating in and contributing to our projects and discussions, you acknowledge that you have read and agree to the [Mozilla community participation guidelines](https://github.com/mdn/mdn-community/blob/main/CODE_OF_CONDUCT.md). + +## Get in touch + +You can communicate with the MDN Web Docs team and community through our [Matrix channel](https://chat.mozilla.org/#/room/#mdn:mozilla.org), forums on [Discourse](https://discourse.mozilla.org/c/mdn/236), and discussions on [GitHub](https://github.com/mdn/mdn-community/discussions). + +- If you are learning web development and are stuck on a coding problem, we have [active forums](https://discourse.mozilla.org/c/mdn/learn/250) where you can ask questions and get help. + +### General support questions + +We are a small team working hard to keep up with the documentation demands of a continuously changing web ecosystem. Unfortunately, we just can't help with general support questions. For general help while learning to code, please refer to the following resources: + +- [Learn web development](https://developer.mozilla.org/docs/Learn) +- [MDN Web Docs learn forum](https://discourse.mozilla.org/c/mdn/learn/250) +- [Stackoverflow](https://stackoverflow.com/questions/) + +Any issues, discussions, or pull requests opened on repositories requesting support will be directed here, then closed and locked. diff --git a/files/en-us/mdn/community/issues/content_suggestions_feature_proposals/index.md b/files/en-us/mdn/community/issues/content_suggestions_feature_proposals/index.md new file mode 100644 index 000000000000000..b3880e228999280 --- /dev/null +++ b/files/en-us/mdn/community/issues/content_suggestions_feature_proposals/index.md @@ -0,0 +1,47 @@ +--- +title: Proposing new content or features for MDN Web Docs +slug: MDN/Community/Issues/Content_suggestions_feature_proposals +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +We are always interested in hearing from our community about new content or feature suggestions you may have for MDN Web Docs. However, even though we are open to suggestions, we have to keep the following in mind: + +- MDN Web Docs is run and managed by a small internal team. We also rely heavily on our partners and community to help us keep MDN Web Docs the best resource for web developers on the web. As such, we will sometimes have to say no to new content or features because we will simply not be unable to maintain them long-term. +- MDN Web Docs is also focused on documenting open web standards; some content might not be a good fit. This does not mean the idea or content is not good, just that MDN Web Docs is not the best place for it. + +Keeping that in mind, if you _do_ want to propose content or features for MDN Web Docs, please follow the below steps. + +## Open a content suggestions and feature proposal issue + +When you go to open a [new issue](https://github.com/mdn/mdn/issues/new/choose), you will find a template called "New content or feature suggestions." This is the issue template to use when suggesting new content or features. The issue template does require quite a bit of information but is very deliberate. + +1. It ensures we have all the information we need to review your proposal without much back and forth. +2. It helps you to think through your proposal as you complete the form. + +Once you have completed the form and submitted the issue, a core team member will get back to you within a week to two weeks, depending on the complexity of your proposal. + +## Participate in the discussion and wait for approval + +If we feel the proposal might be a good fit, we will [start a discussion](https://github.com/mdn/mdn-community/dicsussions) on our MDN community discussions repository. This is to get input from our partners and the wider community. We encourage you to monitor the discussion and join in as appropriate. + +## Opening an issue + +Suppose a consensus is reached that this is content we want to add or a feature we want to build. In that case, we will open an issue against the appropriate repository referencing the original proposal and the discussion and fill in any gaps so the issue is clearly actionable. + +## Work is assigned + +At this point, the work will be prioritized and assigned to those responsible for ensuring it is implemented and reviewed. + +## Open pull request + +Once the work is ready for review, a pull request should be opened, which again references the proposal, discussion, and issue. This ensures that we always have the full context of the work. Finally, the required people will be assigned, and the review process will start. + +## Work is reviewed and merged + +Here again, depending on the complexity of the content or feature, the review stage can be lengthy. We ask for your patience and that you continue to be involved as appropriate. Once we have approval from at least two internal team members, we are ready to merge the pull request. + +This will conclude the entire process, and the content or feature will be available on MDN Web Docs. diff --git a/files/en-us/mdn/community/issues/index.md b/files/en-us/mdn/community/issues/index.md new file mode 100644 index 000000000000000..2adddc3022e1aea --- /dev/null +++ b/files/en-us/mdn/community/issues/index.md @@ -0,0 +1,126 @@ +--- +title: Using GitHub Issues on MDN Web Docs +slug: MDN/Community/Issues +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +[Issues](https://docs.github.com/en/github/managing-your-work-on-github/about-issues) are used to track all bugs and work that has a clear actionable outcome. If you have found a bug with either our content or the platform, please search current open issues against the [relavant repository](../contributing/our-repositories/) to ensure someone has not already reported the issue. If the issue is new, please file an issue using the relavant template available in the repository. + +> NOTE: If an issue has a triage label, we haven't reviewed it yet, and you shouldn't begin work on it. + +If the issue you are filing is not to report a bug, please ensure that it lists actionable tasks or a clear outcome. For example: + +```markdown +## Remove {{ warning }} macro from documents + +We should no longer be using the `{{ warning }}` macro in our documentation. + +### Task description + +We should therefore replace all instances of the `{{ warning }}` macro with the following: + +> **Warning:** Main subject line +> +> Details of the warning. +> It can have multiple paragraphs. + +### Actionable outcome + +- [ ] There are no more instances of the ``{{ warning }}` macro in the `mdn/content` repository. +- [ ] Deprecate `{{ warning }}` macro +- [ ] Notify localisation team leads of the change. +``` + +## Opening an issue + +What info should be included +What we accept and don't accept + +Discussions should be here + + + +Priority: + +- `p0` Urgent: Something is broken and needs to be fixed immediately. +- `p1` High priority: This is needed, but not something that's broken and affecting our users. +- `p2` Medium priority: It would be great to get this done if there aren't any other high priority tasks, chances are this issue will escalate to high priority soon enough. +- `p3` Low priority: This is a nice to have. Small chance of it escalating, but something we should consider. + +## Make progress, not noise + +Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn’t make other contributors jobs harder. Submitting pull requests to fix issues is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise? + +As a rule, do: + +- Use [GitHub discussion](https://github.com/mdn/mdn-community/discussions) before filing an issue. This helps to keep issues focused and productive. +- Ask questions using other mechanisms like [chat rooms](https://chat.mozilla.org/#/room/#mdn:mozilla.org) or [forums](<(https://discourse.mozilla.org/c/mdn/236)>) if you are not sure whether something is useful or have a simple question. +- Read the [contributor documentation]() and [how to write documentation]() first to try to solve the issue yourself. + +Don’t: + +- Complicate issues by trying to discuss multiple topics at once, or making off-topic comments. +- Open lots of issues asking vague questions. +- Ask questions without trying to solve the problem yourself first. + +## Working on an issue + +All repositories have an issue tracker, where you can find tasks to help contribute + +Most repositories have a `help-wanted` label or `good-first-issue` label. Some do not, but this is not a pre-requisite and you are welcome to browse and pick something that is suitable for your skill set. + +Once you've found an issue you'd like to work on, amke sure no one else is assigned to the issue. Add a comment saying you would like to work on it and assign the issue to yourself. + +Most issues need some investigation before work can start, if you need to ask questions + +_(define)_ + +If you take on an issue we expect work to happen in a timely manner. If you can no longer take on the task, leave a comment and unassign yourself. + +Fork and branch the repository, do your work and open a [pull request](linktopullrequest). + +_(more stuff)_ + +Now and then, you may run into problems while using MDN. Whether it's a problem with site infrastructure or an error in documentation content, you can either try to fix it yourself or report the problem. While the former is preferred, the latter is sometimes the best you can manage, and that's okay too. + +The best thing you can possibly do is fix problems you spot yourself — this is done by updating the site source: + +- The MDN content itself is found in the [content](https://github.com/mdn/content) repo. +- The MDN platform code, which renders the content as MDN, is found in the [yari](https://github.com/mdn/yari) repo. + +Both repos include useful information to guide you on how to contribute. + +However, maybe you don't know the answer or are in the middle of a deadline on your own project, and need to jot down the problem so someone can look at it later. + +The way to report a documentation problem by filing an [documentation issue](https://github.com/mdn/content/issues) or [platform issue](https://github.com/mdn/yari/issues), depending on what the problem you've discovered relates to. + +## When choosing a GitHub issue to work on + +1. Write a comment in the issue saying that you would like to take it on, and we'll assign you to it. + + - If someone else is already assigned to the issue: + + 1. If this was more than one week ago, and there has not been much activity, @mention them and ask them if you can take it over, or otherwise help get it to completion. + + - If they agree for you to take it, we'll assign you to it and remove them. + - If they agree for you to take it and some work has been done already, or the agreement is to help them out with it, we'll assign you to it alongside them. + + 2. If it was less than one week ago, then have some patience, and give them a chance to work on it. + +2. If the issue has been marked as complete but needing a review, and you want to review it, @mention them in the comments and say you'll review it. + +## When you've been assigned to an issue + +1. Scope out the remainder of the work that needs to be done. + + - If the issue is well-described, and the work is pretty obvious, go ahead and do it. + - If the issue is not well-described, and/or you are not sure what is needed, feel free to @mention the poster and ask for more information. + - If you are not still sure who to ask, ask for help in the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). + +2. Once you think you've fixed an issue, ask for a review in the comments. +3. Once an issue has been successfully reviewed and comments answered, you can mark it as closed. +4. If you no longer have time to work on an issue, let us know in a comment so we can assign it someone else. diff --git a/files/en-us/mdn/community/issues/issue_triage/index.md b/files/en-us/mdn/community/issues/issue_triage/index.md new file mode 100644 index 000000000000000..bbc4ef75339dfb8 --- /dev/null +++ b/files/en-us/mdn/community/issues/issue_triage/index.md @@ -0,0 +1,11 @@ +--- +title: Issue triage on MDN Web Docs +slug: MDN/Community/Issues/Issue_triage +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +_(see meta docs)_ diff --git a/files/en-us/mdn/community/learn_forum/index.md b/files/en-us/mdn/community/learn_forum/index.md new file mode 100644 index 000000000000000..e95b91dce684589 --- /dev/null +++ b/files/en-us/mdn/community/learn_forum/index.md @@ -0,0 +1,84 @@ +--- +title: MDN Web Docs Learn Forum +slug: MDN/Community/Learn_forum +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +Our [Learn web development](/en-US/docs/Learn) pages get over a million views per month, and have [active forums](https://discourse.mozilla.org/c/mdn/learn/250) where people go to ask for general help, or request that their assessments be marked. We'd love some help with answering posts, and growing our learning community. + +## What do we need help with? + +In the [MDN learning forum](https://discourse.mozilla.org/c/mdn/learn/250), there are two main types of post that we'd like you to help out with answering: + +1. General questions about web development. +2. Specific questions asking for help or assessment with the skill tests and assessments that appear on the Learn web development section on MDN. + +## How can you benefit? + +- Helping people with their code problems is a great way to learn more about web technologies — as you research a solution and write an answer to someone's question, you will gain a deeper understanding of the subject, and improve your skills. +- As you get more involved in the MDN community, you'll get to know Mozilla staff and other community members, giving you a valuable network of contacts for getting help with your own issues and increasing your visibility. +- Helping to answer coding questions is largely its own reward, but it will also demonstrate your expertise in web technologies and possibly even help you with your course, or job opportunities. + +## What skills do you need? + +- You should be knowledgeable in web technologies such as HTML, CSS, and JavaScript. Ideally you should also be good at explaining technical topics, and enjoy helping beginners learn to code. +- The language of the forum is English — you should have a reasonable proficiency with the English language, but it really doesn't need to be perfect. We have people from all over the world visiting our forums, and we want everyone who visits us to feel as comfortable and included as possible. + +## How to help + +1. First of all, [sign up for an MDN account](/en-US/docs/MDN/Contribute/Getting_started#step_1_create_an_account_on_mdn), if you don't already have one. You don't absolutely need to do this to help in the learning area, but it will be useful in the long run. +2. Also sign up for [Mozilla Discourse](https://discourse.mozilla.org/), if you haven't already. +3. Have a look at [Learn web development](/en-US/docs/Learn) section and gain a basic level of familiarity with what's there, if you haven't already (see the [Structure of the MDN Learning Area](#structure_of_the_mdn_learning_area) section below for help). + +### Once you are set up + +1. Have a look at the [learning forum](https://discourse.mozilla.org/c/mdn/learn/250) and see if there are any posts that have no replies — this is the best place to start. + + - Hint: If you can't find any that have no replies, check some of the other ones that were recently updated and see if you can add anything useful that has not already been said. + +2. If the post you are replying to is a general ask for help, reply to them, and give them as much help as you've got time for. +3. If the post you are replying to is requesting an assessment for one of the "test your skill"/"assessment" tasks: + + 1. Identify which article/task is being assessed, and find the associated marking guide for it. It is totally OK to ask the person who submitted the post if they can give you the link to the assessment/skill test. + 2. Identify the person's code — they should give it to you in the form of a codepen/jsfiddle/jsbin link, or similar. If they don't provide it in a form that is easy to assess, it is perfectly OK to ask them to put it in codepen, jsfiddle, or similar. + + - A common problem is when people post their code directly into a discourse message — discourse renders HTML elements and turns quotes into smartquotes, which breaks code. It is much better to get it sent over as a URL to a shareable code editor app. + + 3. Read through the code and assess it + + 1. Does it work, and does it give you the result that it should give? + 2. If not, why doesn't it work? + 3. Are there any tips you can give the person to make the code better (more efficient, best practice, etc.)? + + 4. Give them a report on how they did: + + 1. Some of the marking guides suggest a marking scheme with points for each bit of the question, but you don't need to be that accurate. + 2. If the person did great except for a few nitpicks, tell them the nitpicks, but give them lots of praise too. + 3. If the person was nearly there but it wasn't quite right, tell them they did great, but then share the fixes they'd need to make it work, and perhaps even link to the marking guide so they can see what we did. + 4. If the person is not really anywhere near a working solution, be kind and encouraging and try to give them a few clues as to what direction they should go in. Give them another chance to try to do it better. + 5. If you need assistance with anything, ask for help in the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). + +> **Note:** Important: Above all, be patient, be friendly, be kind. Remember — most of these folks are beginners. + +## Structure of the MDN Learning Area + +When helping answer questions related to the [Learn web development](/en-US/docs/Learn) section of MDN, it is a good idea to have a look around it and gain a basic level of familiarity with what's there. + +1. Have a look through the page structure in general. +2. Especially look at the types of assessments available, + + - from the numerous "test your skills" articles available (e.g. see [/en-US/docs/Learn/JavaScript/Building_blocks/conditionals#Test_your_skills!](/en-US/docs/Learn/JavaScript/Building_blocks/conditionals#test_your_skills!)) + - to the more in-depth assessments at the end of some modules (e.g. see [/en-US/docs/Learn/JavaScript/Building_blocks/Image_gallery](/en-US/docs/Learn/JavaScript/Building_blocks/Image_gallery)) + +3. Have a look at the GitHub repos associated with the learning area (most of the files are available in , some are in ). Most of the examples learners will want help with are contained here. +4. Each assessment/skill test has an associated marking guide and recommended solution available, to help you assess their work. +5. There are patterns that make it easier to find these resources, for example: + + - The above "test your skills" marking guide and resources are available at . + - The above assessment marking guide and resources are available at . + +It will seem tricky to navigate around all this to begin with, but you'll find it easier in time, as you become more familiar with the exercises. diff --git a/files/en-us/mdn/community/mdn_content/index.md b/files/en-us/mdn/community/mdn_content/index.md new file mode 100644 index 000000000000000..9c23a9df19fd7af --- /dev/null +++ b/files/en-us/mdn/community/mdn_content/index.md @@ -0,0 +1,53 @@ +--- +title: Contributing to MDN Web Docs content +slug: MDN/Community/MDN_content +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance + - mdn-content +--- + +Problems with MDN docs are reported as [content repo issues](https://github.com/mdn/content/issues). This article helps you find the _best_ issues to work on, based on your expertise and how much time you have available, and outlines the main steps to fixing them. + +> **Note:** We get a lot of content bugs — any help you can give in fixing them is very much appreciated! + +## What do we need help with? + +To help you choose what content issues to work on, we've sorted them using GitHub labels. + +The labels below help you find tasks based on how much time you have available. + +| Label | Description | +| ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [Less-than-30-minute tasks on the content repo](https://github.com/mdn/content/issues?q=is%3Aissue+is%3Aopen+label%3A%22time%3A+-30mins%22) | A task that will probably take less than 30 minutes. | +| [Less-than-3-hour tasks on the content repo](https://github.com/mdn/content/issues?q=is%3Aissue+is%3Aopen+label%3A%22time%3A+-3hr%22) | A task that will probably take less than 3 hours. | +| [Less-than-2-day tasks on the content repo](https://github.com/mdn/content/issues?q=is%3Aissue+is%3Aopen+label%3A%22time%3A+-2days%22) | A task that will probably take less than 2 days. | + +If you'd prefer to browse your tasks and choose by technology category instead, you can also find content type labels on [issues in the content repository](https://github.com/mdn/content/issues). + +## How can you benefit? + +- Fixing MDN content bugs is a great way to learn more about web technologies — as you research a problem and create the required content, you will gain a deeper understanding of the subject, and improve your skills. +- As you get more involved in the MDN community, you'll get to know Mozilla staff and other community members, giving you a valuable network of contacts for getting help with your own issues and increasing your visibility. +- Helping to fix problems is largely its own reward, but it will also serve as a record of your open source contributions, demonstrating your expertise in web technologies and possibly even helping you with your course, or job opportunities. + +## What skills do you need? + +- You need to be knowledgeable in the topic areas that you choose to help with (e.g. JavaScript, CSS). +- Most of the examples and pages that you will help with are written in English, so you should have a reasonable understanding of the English language. But don't worry if your English is not perfect! Our team is more than happy to help clean up any writing. + +## How to help + +1. First of all, sign up for a [GitHub account](https://github.com/join), if you don't already have one — you'll need this to communicate on the GitHub issues. +2. Next, choose one or more topic areas you'd like to help with. Use the list above to get more information to help you make your selection. If you are not sure what a good choice would be, ask for help in the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). + +### Once you are set up + +1. Choose an issue to work on that interests you, and ask us to assign it to you with a comment on the issue. +2. If you need any help when you are working on it, feel free to contact us in the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). +3. Once you've fixed an issue, ask the submitter for a review and, hopefully, they will tell you whether they think more work is required. We will get involved if needed. +4. Once the issue is verified fixed, it can be closed. The person closing the issue can be either the original issue submitter, or an MDN staff member. + +> **Note:** When choosing and working on an issue, you might also find our [GitHub best practices](/en-US/docs/MDN/Contribute/GitHub_best_practices) and [Getting started on MDN](/en-US/docs/MDN/Contribute/Getting_started) guides useful. diff --git a/files/en-us/mdn/community/mdn_content/issues/index.md b/files/en-us/mdn/community/mdn_content/issues/index.md new file mode 100644 index 000000000000000..0bc97f53f297181 --- /dev/null +++ b/files/en-us/mdn/community/mdn_content/issues/index.md @@ -0,0 +1,12 @@ +--- +title: Using Issues on MDN Content +slug: MDN/Community/MDN_content/Issues +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance + - mdn-content +--- + +TBD diff --git a/files/en-us/mdn/community/mdn_content/pull_requests/index.md b/files/en-us/mdn/community/mdn_content/pull_requests/index.md new file mode 100644 index 000000000000000..9a00c73539f5f3a --- /dev/null +++ b/files/en-us/mdn/community/mdn_content/pull_requests/index.md @@ -0,0 +1,61 @@ +--- +title: Pull Request Etiquette and Process for MDN Content +slug: MDN/Community/MDN_content/Pull_requests +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance + - mdn-content +--- + +## Overall process + +This section describes how contributors make changes on MDN Web Docs and how the changes are reviewed and land on the site. + +### Types of content changes on MDN Web Docs + +Content changes we get on MDN Web Docs are related to a variety of work streams, some of which include: + +- **Day-to-day content improvement work**: This includes documentation of new APIs, new CSS properties, and other significant content additions. This is usually done by MDN Web Docs staff working for Mozilla, Google, Open Web Docs, Samsung, etc., but also sometimes by community volunteers. +- **"Drive-by” fixes**: This includes small updates done to the site to fix typos, grammatical issues, and technical inaccuracies. These issues are usually found by users of MDN Web Docs. +- **Content bug fixes**: These are usually done by volunteers to close issues on mdn/content repo. + +### How content changes are reviewed + +Regardless of how content changes are done, they will be submitted as pull requests on this repo, which requires rapid reviewing and merging to ensure that the site does not get out-of-date. This is managed in the following way: + +1. **Reviewer assignment**: Different MDN staff members and volunteers have been assigned as "topic review owners", meaning that when a pull request related to a particular topic area of the site (e.g. the CSS reference, or the learning area) is opened, it will be assigned to that area's topic review owner(s). This is handled using the CODEOWNERS file, in which particular content directories are assigned to the respective reviewing team. +2. **Review, approval, merge**: Once the review has been done and the pull request has been approved, the assigned reviewer merges the pull request. +3. **Content update on the site**: The site is rebuilt once every 24 hours to ensure that the content does not get too stale. So volunteers can see their changes go live after 24 hours. + +### Things to consider before opening a pull request + +These guidelines apply to anyone opening a PR to make a change on MDN Web Docs. + +- **Open issue or discussion before opening PR**: If your PR would contain any kind of significant complexity (for example, it contains technical changes and isn't just a typo fix, grammatical improvement, or a formatting/structural change), please open an [issue](https://github.com/mdn/content/issues/new/choose) or [discussion](https://github.com/mdn/mdn-community) to describe why you're making the change, how the change would improve the content, and anything else we need to know about the change. Specifically for content suggestions or feature proposals, we have a [well documented](../../issues/content-suggestions-feature-proposals/) process to follow. +- **Keep the PR short (1 issue per PR)**: Each PR should contain a single logical change or a related set of changes that make sense to submit together. If a PR becomes too large or contains too many unrelated changes, it becomes too difficult to review, and may begin to look suspicious (it is easier to hide malicious changes in a large PR. In such cases, the reviewer has the right to close your PR, and ask that you submit a separate PR for each logical set of changes that belong together. It is also good practice to reference the relevant issue in your PR description using [GitHub’s special syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). This helps maintenance as GitHub will automatically close linked issues once the PR is merged. +- **PR to update grammar**: PRs should not contain large amounts of grammar updates. Seemingly insignificant changes can change the meaning of technical content, so these need a careful review. Keep in mind that MDN Web Docs contains technical documentation; you should not report basic improvements in the grammar but only cases where the grammar is clearly incorrect. +- **PR to update a demo repository**: For PRs that update API usage, there needs to be an accompanying PR on the mdn/content repository to update the corresponding relevant documentation. Such a PR can be rejected if there is no corresponding content PR. +- **Only enable auto-merge for approved PRs**: It is not a recommended practice to select the “Enable auto-merge (squash)” checkbox on your PRs that are waiting to be reviewed or approved. + +### Guidelines for after submitting a pull request + +We have general guidelines for what to do and expect after a PR has been opened. Please [refer to these guidelines](../../pull-requests/). + +### Guidelines for pull request review assignments + +These guidelines apply to anyone who is tasked with reviewing MDN content PRs. + +#### If you are the assigned reviewer + +- **Add a starting comment**: Add a comment as soon as possible that you are aware of the PR and will start the review soon. This is an important step to avoid someone else reviewing the PR at the same time as you and so that others know it’s on your radar for review. +- **Ask for information from the PR author**: You can request more information to help with your review if the PR author has not explained why they are making this change. Ideally, they should reference an issue that they’re trying to fix in this PR. +- **Ask for help**: If you’re open to receiving or want technical help with the review, add the `review-help-needed` label. + +If you don't understand a content change that you've been selected to review or feel that it is too large and complex for you to deal with, don't panic! Feel free to reach out to someone else to ask for help, like a colleague or someone else in your group of topic review owners (if you know who they are). If you are not sure who to approach for help, then ping our `@mdn/core-yari-content` group to ask for help. + +Related to the above point, it is rare that you'll be required to review a large, complex content change with no warning, like a complete page rewrite, or the addition of several new reference pages or tutorials. Usually such changes are done as part of specific work streams where the content has been approved for addition and reviewer(s) have been assigned already. In such cases, the PR should be linked to an issue that explains all these details. If you are not sure, ask the PR author if they need a review of the content, and where the rationale behind the change is explained. Ping our team on [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) to ask for help if you are still not sure or if you think the content is suspicious. + +- **Close PR with unrelated changes**: You have the right to close a PR if it is too complex and/or contains multiple unrelated changes and ask the PR author to submit their changes in smaller atomic chunks. +- **Ask for load balancing help**: If your plate is full at the moment and you don’t think you will be able to complete the review in a timely manner, copy the `@mdn/core-yari-content` team and ask if someone else can take up the review. diff --git a/files/en-us/mdn/community/open_source_etiquette/index.md b/files/en-us/mdn/community/open_source_etiquette/index.md new file mode 100644 index 000000000000000..3ec0f7deedde64e --- /dev/null +++ b/files/en-us/mdn/community/open_source_etiquette/index.md @@ -0,0 +1,139 @@ +--- +title: Open Source Etiquette +slug: MDN/Community/Open_source_etiquette +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance + - open-source +--- + +If you've not worked on an open source project (OSP) before, it is a good idea to read this article before starting to contribute to MDN Web Docs (or other open source projects). There are a few best practices to adopt that will help ensure that you and the other project contributors feel valued and safe, and stay productive. + +This article won't teach you everything about contributing to open source; the aim here is more to give you some good starting points to think about as you get started with open source contributions. + +## Think about why you are contributing to an OSP + +Before you start contributing to an open source project, ask yourself why you want to do that. It is fine if the answer to this question is just "I'm bored and I want to find something productive to do with my time", but you can probably go deeper than that. + +Even better reasons might include: + +- I use this tool all the time and found a bug in it/want to help make it better. +- I want to help other people use the tool more successfully. +- I want to help other people contribute to the project more successfully. +- I want to improve my own skills. +- I want to publicly demonstrate my own skills as part of my college or university course. +- I want to publicly demonstrate my own skills to improve my chances of getting a job. + +Some of these reasons are self-serving, and that's OK — if you are spending your time working on a project for free, then it is fair to expect to get something out of it. In addition, having a clear set of reasons for contributing will make it easier to decide what to work on first. + +Your presence on the project should be productive, and it shouldn't stop others from being so too. + +## Be polite, be kind, avoid incendiary or offensive language + +We could abbreviate this to "be kind". This is our number one bit of advice for anyone starting open source contributions. + +Be kind to the other contributors on the project, and it will be a happier and more productive place. This includes: + +- Thanking people if they help you. +- Congratulating people where appropriate (for example if they land their first ever pull request, or fix a particularly difficult bug). +- Always responding respectfully to people, even if you feel like the answer to their question was a bit obvious, or that they are repeating themselves. +- Trying to help people to do better next time, in a supportive way, e.g. during pull request reviews or as you answer their questions. Saying "this is wrong" or "here is the answer" is nowhere near as helpful as saying "This is OK, but I feel that this would be better if you tried doing it more like this, here's a blog post for more ideas" or "you can find the answer here; also check out this link for more common answers". + +You and the other contributors are (or should be) here because they want to make a positive contribution to the project, but beyond that, you can't assume anything about them. This includes their: + +- Knowledge of the project and the technologies used to build it +- Gender, sexuality, age, languages spoken, location, political views, religion, or other personal attributes +- Experience with open source projects +- Confidence +- Expectations +- Sense of humor + +You should therefore keep what you write on topic as much as possible, staying away from potential controversial off-topic subjects like religion or politics, and being supportive and respectful even if you disagree with someone, or don't like a decision they've made. + +Also, you should refrain from any swearing / offensive language, even if it is not directed at anyone in particular. It is not needed for participation, and some people are really sensitive to it. + +Be aware that there are rules in place in any good OSP to protect its contributors against being made to feel uncomfortable while contributing. This usually comes in the form of a CODE_OF_CONDUCT.md file on GitHub. + +For example, MDN's repos are governed by the wide-reaching [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). Usually mildly offensive behavior on MDN Web Docs repos (such as constantly being off-topic/disruptive, or being rude) will usually be first responded to by a warning on the repo, followed by a final warning, then a temporary or permanent ban. More serious behavioral problems such as hate speech or threats against another contributor will not be tolerated, and will likely result in an instant ban. + +If you receive anything that makes you feel uncomfortable, you should always report it using the mechanism provided on the code of conduct. + +## Choose effective contributions + +Think about what you want to do on the project. For example, we have a large list of issues filed at on the [contributtors task board](https://github.com/orgs/mdn/projects/25/views/1), broken up by various task types. + +You could also contribute by opening [pull requests](../pull-requests/) to fix problems that you come across while reading MDN articles. + +A lot of the work on MDN revolves around writing documentation and code examples, but there are other ways to contribute too: + +- Help to triage issues that come in. +- Help fix typos. +- Help to improve grammar and make pages more understandable. +- Help to mentor people that are trying to make fixes. + +Every fix is useful, no matter how small, and we won't turn any fix away. Nevertheless, try to make sure your fixes are productive. We'd like to advise against these kinds of contributions: + +- Updating code styling just because "you like that style better". +- Updating language style "just because you like that style better". +- Changing pages from US English to British English. +- Adding or removing a bunch of punctuation when there's not really anything wrong. +- Changing the testing framework we are using for something else because you prefer it. + +In many cases, things are like they are on OSPs for a reason. You should read their style guides if they have one, and if in doubt about whether something is productive, always ask first! + +## Read the manual + +Good OSPs will always make contributor documentation readily available. On GitHub projects, it is usually in the repo's CONTRIBUTING.md file, or sometimes in the project's README.md file. Being a documentation project, MDN content has a [README](https://github.com/mdn/content/blob/main/README.md) and a decent set of contributor docs on the site itself (see [Contributing to MDN](/en-US/docs/MDN/Contribute)). + +Don't be afraid to ask for help, but ALWAYS try to find the answer to your question first before asking. This way you build up your knowledge of the project and become more independent, and don't put unnecessary burden on the other contributors. + +Of course, the docs won't always be perfect. If an explanation is hard to find or not described very well, file an issue, or create a pull request to try to fix it yourself. + +## Find out where to ask questions + +Always find out where the best place is to ask questions. Good OSPs will always make this clear in their docs (see [ask for help on MDN](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help)). If you want to ask general questions, then always make use of these channels. Don't just file an issue on GitHub for every question, as it adds noise to the project (see "Make progress, not noise" below). + +## Make progress, not noise + +Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn't make other contributor's jobs harder. Submitting pull requests to fix bugs is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise? + +As a rule, do: + +- Discuss one topic per issue — it is easy to keep issues focused and productive. +- Fix one issue per PR — it may be slightly more work for you, but it is much easier to review a single clear fix. +- Contribute to other threads if you have a useful point to make or can answer someone else's question. +- Ask questions using other mechanisms like chat rooms or forums if you are not sure whether something is useful or have a simple question. +- Read the manual first to try to answer the question yourself before asking it. + +Don't: + +- Complicate issues by trying to discuss multiple topics at once, or making off-topic comments. +- Try to cram multiple fixes into a single pull request. It makes it a lot harder to review, and raises suspicions (some people might think you are trying to hide some malicious code in between the valid changes). +- Open lots of issues asking vague questions. +- Ask questions without trying to solve the problem yourself first. + +## OSPs are a democracy (almost) + +OSPs are quite democratic — many decisions are voted on, and you are largely free to contribute how you want, as long as you don't impede anyone else from contributing. + +However, some things will be largely decided by a small group of core contributors. You are free to make a case against any decision, but sometimes a moderator will make a call that goes against your opinion. You need to respect and accept these decisions. + +It is useful to get to know any project's moderators, so you know who best to ask for help, for example in pull requests or issue threads. + +## Be patient, be timely + +Bear in mind that many people working on OSPs are doing it in their free time, without payment, and all people working on OSPs are generally very busy. If you are waiting for something like a pull request review, or an answer to a question, be patient. + +It is reasonable to wait a few days and then ping someone politely to ask if they've had time to look at it. If they happen to be too busy, it may be best to wait a further week and try following up with them then. + +It is NOT reasonable to start demanding things, like a quick reply. + +If someone is waiting for you to do something for them, you should be extended the same courtesy, but at the same time, try to respond as promptly as you can. If you really can't find the time, let them know, and ask the maintainers to help you find someone else to do the task. + +## See also + +- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) +- [More general freeCodeCamp "How to contribute to open source" list](https://github.com/freeCodeCamp/how-to-contribute-to-open-source) +- [Getting started with contributing to open source](https://stackoverflow.blog/2020/08/03/getting-started-with-contributing-to-open-source/) diff --git a/files/en-us/mdn/community/pull_requests/index.md b/files/en-us/mdn/community/pull_requests/index.md new file mode 100644 index 000000000000000..3ba695eec2f7d7f --- /dev/null +++ b/files/en-us/mdn/community/pull_requests/index.md @@ -0,0 +1,132 @@ +--- +title: MDN Web Docs Pull Request Guidelines +slug: MDN/Community/Pull_requests +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +## Guidelines for after submitting a pull request + +- **Handle test failures**: When you submit a PR, a number of tests are automatically run as [GitHub Actions](https://github.com/features/actions). If one or more of these tests fail, it is your responsibility to try and resolve the underlying issue(s). If you don't know how to resolve the underlying issue(s), you can ask for help. Your PR will not be approved and merged if there are failing tests. +- **Resolve merge conflicts**: If your PR has [merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts) with the main branch (GitHub checks for this automatically and notifies you), you are responsible for resolving them. You have two options here: + - For simple merge conflicts, you can use the [GitHub UI](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github) to resolve the conflicts. + - For more complex merge conflicts, you should use the [command line(terminal)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line) to resolve the conflicts. +- **Don’t reopen closed PRs**: Don’t re-open a PR that a reviewer has closed unless there has been a discussion and a consensus reached to do so. In most cases it is best to open a new PR and reference the previous PR. + +## Reviewing pull requests + +This document describes the review process for content changes on MDN Web Docs, and is for use by those who have been tasked with reviewing MDN content PRs. + +## Process for reviewing content changes + +Content changes we get on MDN are related to a variety of work streams, +for example: + +- Day-to-day content improvement work — new APIs, new CSS properties, and + other significant platform updates and content additions, usually done + by MDN staff working for Mozilla, Google, Open Web Docs, Samsung, etc., + but also sometimes by community volunteers. +- "Drive-by fixes" — small updates done to the site to fix typos, grammatical issues, and technical inaccuracies, usually as they are found by readers of MDN Web Docs. +- MDN content bug fixes, usually done by volunteers to close issues on this repo. + +Regardless of how a content change is done, they will be submitted as +[pull requests](https://github.com/mdn/content/pulls) on this repo, which will require rapid reviewing and merging to ensure that the site does not get out-of-date. This is being handled as follows: + +1. Different MDN staff members and volunteers have been assigned as "topic + review owners", meaning that when a pull request comes in related to a + particular topic area of the site (e.g. the CSS reference, or the learning area), it will be assigned to that area's topic review owner(s) and they will receive an e-mail notification asking for a review. This is being handled using a [CODEOWNERS](https://github.com/mdn/content/blob/main/.github/CODEOWNERS) file, in which particular content directories are assigned to the topics review owner's GitHub usernames. +1. Once the review has been done and the pull request has been approved, the + reviewer should also merge the pull request. +1. The site will be rebuilt once every 24 hours to ensure that the content + does not get too stale. + +## Review guidelines + +If you are reviewing mdn content changes, read through the following +guidelines. There’s quite a lot here, but don’t worry if you don’t review +perfectly in accordance with all of these points immediately. It is more +important to make sure the content is readable, useful, correct, and not +inappropriate, than it is to follow every guideline to the letter. + +1. Familiarize yourself with the [MDN Code example guidelines](../../how-to-write/writing-style-guide/code-example-guidelines/index.md) and make sure that code examples follow the guidelines. You’ll get used to them eventually, and we are intending to automatically lint against our guidelines at some point in the future. +1. Familiarize yourself with the [MDN Writing style guide](../../how-to-write/writing-style-guide/index.md), and use it to inform your reviews of new text content. +1. Familiarize yourself with the MDN [pull request guidelines](https://github.com/mdn/content/blob/main/README.md#pull-request-etiquette). + The key points here are + - You have the right to request more information to help your review if the submitter has not explained why they are making this change. + - You have the right to close a pull request if it is too complex and/or contains multiple unrelated changes and ask the submitter to submit their changes in smaller atomic chunks. +1. When reviewing a pull request, use the [GitHub review tools](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). Use "Request changes" when submitting a review that will require the submitter to do some more work, or "Approve" if the submission is ready to add and you want to merge it. [Reviewing proposed changes in a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) is also useful if you want more information. +1. Be polite and constructive at all times when writing review comments, or otherwise interacting with the submitter and other community members. We are all bound by [our Code of Conduct](CODE_OF_CONDUCT.md) when contributing to MDN, which means adhering to Mozilla's [Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). If anyone has engaged in behavior that is potentially illegal or makes you or someone else feel unsafe, unwelcome, or uncomfortable, you are encouraged to [report it](https://www.mozilla.org/en-US/about/governance/policies/participation/reporting/). We want MDN to be a welcoming, friendly community that we can all be proud of. +1. If a pull request is fine apart from a small typo or some other minor issue, you might want to just fix the issue yourself rather than ask the submitter to change it. You can do this provided the PR has been set up to allow changes (see [Allowing changes to a pull request branch created from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) for more details). If you are not sure how to make changes to someone else’s pull request, [@vkWeb](https://github.com/vkWeb/) wrote some nice simple instructions on how to do this on the command line; see [ReviewPRCommands](https://gist.github.com/vkWeb/dcec82b079f1edc19478ddb58b0ffc5e). + - Alternatively, you can edit files using the GitHub UI — go to the pull request’s "Files changed" tab, find the file you want to edit, and choose "three dot" menu (...) > Edit file. +1. If you don’t understand a content change that you’ve been selected to review, or feel that it is too large and complex for you to deal with, don’t panic! Feel free to reach out to someone else to ask for help, like a colleague, or someone else in your group of topic review owners (if you know who they are). If you are not sure who to approach for help, then ping our `@core-yari-content` group to ask for help. +1. Related to the above point, it is rare that you’ll be required to review a large, complex content change with no warning, like a complete page rewrite, or the addition of several new reference pages or tutorials. Usually such changes are done as part of specific work streams where the content has been approved for addition, and reviewer(s) have been assigned already. In such cases, the PR should be linked to an issue that explains all these details. If you are not sure, ask the submitter if they need a review of the content, and where the rationale behind the change is explained. Ping our team on [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) to ask for help if you are still not sure, or if you think the content is suspicious. + +Note: You may encounter merge conflicts as you review pull requests, if a another pull request that touches some of the same files got merged before the one you are reviewing. [Addressing merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts) is a useful resource to help you. Feel free also to ask your team(s) for help if you need it. + +## Specific reviewer overrides on pull requests + +Some of the pull requests submitted on the `content` repo relate to specific workstreams being undertaken by browser vendors or other organizations that have a defined set of writers and reviewers. In these cases, the submitter of the PR will include the username of the reviewer in a line at the bottom of the pull request description, for example: + +`reviewer: @jpmedley` + +Upon submitting the pull request, they will request a review from the reviewer specified in the pull request description. Once that reviewer has approved the new content, they will then ask you for an approval as required by the `CODEOWNERS` system for the pull request to be mergeable. + +Therefore, if you receive a pull request review request and then see that you have been overridden with another reviewer in the manner described above, then don't review the pull request — just wait for an approval request. + +## Topic review owners + +The following specific topic areas are being reviewed by the kind souls listed underneath them. Be kind to them, and thank them for all the help they give to this project. If you would like to help with MDN content reviews, +[get in touch with us](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Getting_started#Step_4_Ask_for_help). + +Note that changes to any content areas not explicitly listed below will be handled by the [@core-yari-content](https://github.com/orgs/mdn/teams/core-yari-content) team. + +- [Web accessibility content](https://github.com/orgs/mdn/teams/yari-content-accessibility) +- [General learning content](https://github.com/orgs/mdn/teams/yari-content) +- [CSS learning content](https://github.com/orgs/mdn/teams/yari-content-css) +- [Server-side learning content](https://github.com/orgs/mdn/teams/yari-content) +- [MDN meta docs](https://github.com/orgs/mdn/teams/yari-content) +- [Firefox Developer Tools content](https://github.com/orgs/mdn/teams/yari-content) +- [Mozilla Add-ons reference content](https://github.com/orgs/mdn/teams/yari-content-mozilla-add-ons) +- [HTTP reference content](https://github.com/orgs/mdn/teams/yari-content-http) +- [CSS reference content](https://github.com/orgs/mdn/teams/yari-content-css) +- [HTML reference content](https://github.com/orgs/mdn/teams/yari-content-html) +- [JavaScript reference content](https://github.com/orgs/mdn/teams/yari-content-javascript) +- [Web API reference content](https://github.com/orgs/mdn/teams/yari-content-web-api) +- [SVG reference content](https://github.com/orgs/mdn/teams/yari-content-svg) +- [WebAssembly reference content](https://github.com/orgs/mdn/teams/content-webassembly) + +### Reviewer alumni + +The following folks used to be in one or more of our review teams, but no +longer have the time to contribute; we want to give them our sincere thanks +for all their help. + +- [@vkWeb](https://github.com/vkWeb/) +- [@ericwbailey](https://github.com/ericwbailey) +- [@chrisdavidmills](https://github.com/chrisdavidmills/) +- [@mirunacurtean](https://github.com/mirunacurtean) + +## Make progress, not noise + +Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn’t make other contributors jobs harder. Submitting pull requests to fix issues is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise? + +As a rule, do: + +- Fix one issue per PR — it may be slightly more work for you, but it is much easier to review a single clear fix. +- Ask questions using other mechanisms like [chat rooms](https://chat.mozilla.org/#/room/#mdn:mozilla.org) or [forums](<(https://discourse.mozilla.org/c/mdn/236)>) if you are not sure whether something is useful or have a simple question. +- Read the [contributor documentation]() and [how to write documentation]() first to try to answer the question yourself before filing a pr. + +Don’t: + +- Try to cram multiple fixes into a single pull request. It makes it a lot harder to review, and raises suspicions (some people might think you are trying to hide some malicious code in between the valid changes). + +## Opening a pull request + +## Reviewing a pull request + +## Pull requests we accept + +## `idle` pull requests diff --git a/files/en-us/mdn/community/users_teams/index.md b/files/en-us/mdn/community/users_teams/index.md new file mode 100644 index 000000000000000..a807cbb459bc3d1 --- /dev/null +++ b/files/en-us/mdn/community/users_teams/index.md @@ -0,0 +1,110 @@ +--- +title: MDN Web Docs Users and Teams +slug: MDN/Community/Users_teams +page-type: mdn-community-guide +tags: + - meta + - community-guidelines + - governance +--- + +The success and growth of MDN Web Docs is thanks, in large part, to our community of contributors. There are also employees, contractors and a network of partners who are dedicated to the health, growth and maintenance of the project as a whole. There are also some individuals who have committed a portion of their time to assist with the daily tasks of running MDN Web Docs. These people are part of our invited experts program. To manage all these different groups, we rely heavily on roles and teams within our GitHub organisation. + +A list of the members of the organisation can be [found here](https://github.com/orgs/mdn/people). + +## Teams + +- **Core**: Core MDN Web Docs Team. +- **Localisation team leads**: The people who lead our individual localisation teams. +- **MDN Community Engagement**: People responsible for community engagement across our repositories. +- **MDN Product**: People responsible for the MDN Plus product. +- **OWD**: Contributors from the Open Web Docs non-profit organisation. +- **SRE**: The site reliability engineers that support MDN Web Docs. +- **Yari content**: The umbrella team for all MDN Web Docs content reviewers. + - **Yari content MDN**: Responsible for reviewing docs under /en-US/docs + - **Yari content Mozilla Add-ons**: Responsible for reviewing docs under /en-US/docs/Mozilla/Add-ons + - **Yari content JavaScript**: Responsible for reviewing docs under /en-US/docs/Web/JavaScript + - **Yari content HTML**: Responsible for reviewing docs under /en-US/docs/Web/HTML + - **Yari content Web API**: Responsible for reviewing docs under /en-US/docs/Web/API + - **Yari content HTTP**: Responsible for reviewing docs under /en-US/docs/Web/HTTP + - **Yari content CSS**: Responsible for reviewing docs under /en-US/docs/Web/CSS + - **Yari content accessibility**: Responsible for reviewing docs under /en-US/docs/Web/Accessibility + - **Yari content SVG**: Responsible for reviewing docs under /en-US/docs/Web/SVG + - **Yari content Web Assembly**: Responsible for reviewing docs related to WebAssembly +- **Yari content ES**: Responsible for reviewing `es` docs on MDN +- **Yari content ES**: Responsible for reviewing `fr` docs on MDN +- **Yari content JA**: Responsible for reviewing `ja` docs on MDN +- **Yari content KO**: Responsible for reviewing `ko` docs on MDN +- **Yari content PT-BR**: Responsible for reviewing `pt-br` docs on MDN +- **Yari content RU**: Responsible for reviewing `ru` docs on MDN +- **Yari content ZH**: Responsible for reviewing `zh` docs on MDN + +### What it means to be in a team + +We manage teams using the [GitHub teams feature](https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams). When you are added to a team it means that you have communicated your intent to be more closely involved in the project. This also means that you have some additional responsibilities and rights. + +1. A person on a team is commonly added to the [CODEOWNERS](https://github.com/mdn/content/blob/main/.github/CODEOWNERS) file for their respective area(s) as detailed above. +2. Based on the CODEOWNERS file, you will be automatically assigned to pull requests using a [load-balancing algorithm](https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team#routing-algorithms) when a pull request touches files in your area of responsibility. +3. Members of a team have higher level repository access assigned. Repository permissions are assigned to only those repositories a member need access to. + +## Requesting to be added to a team + +If you wish to become a member of a team you should start by [filing an issue in this repository](https://github.com/mdn/mdn/issues/new/choose). + +To become a member of a team, you are required to: + +- Agree to abide by our [Code of conduct](../../CODE_OF_CONDUCT.md). +- Agree to Mozilla's [Commit Access Requirements](https://www.mozilla.org/en-US/about/governance/policies/commit/requirements/). +- Set up [Two factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) on your GitHub account. + +Once you have filed your issue, someone from our team will review it, and give you the necessary privileges provided our requirements are satisfied. + +## Invited experts + +On MDN Web Docs we have a commitment to document the open web. Not only does this mean that there is a large base of constantly evolving documentation to write and maintain, but we cannot possibly have intimate knowledge of all areas of the open web. To help fill in the gaps we started the invited experts program. + +Invited experts are individuals that have demonstrated in depth knowledge in a particular area, were nominated by the community, our partners, or the MDN Web Docs internal team. + +Invited experts should: + +- Agree to abide by our [Code of conduct](../../CODE_OF_CONDUCT.md). +- Agree to Mozilla's [Commit Access Requirements](https://www.mozilla.org/en-US/about/governance/policies/commit/requirements/). +- Set up [Two factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) on your GitHub account. + +Invited experts are also: + +- Invited to our weekly MDN Web Docs editorial call. +- Invited to our invited experts channel on Matrix. +- Added to the relevant topic team(s) for automatic PR assignments. +- Assigned merge privileges to the repositories where they will review pull requests. + +If you wish to nominate someone to be considered as an invited expert, start by [filing an issue in this repository](https://github.com/mdn/mdn/issues/new/choose). + +## Volunteer and partner maintainers + +MDN Web Docs also have volunteers and partners who are assigned maintainer rights to certain repositories. This is the highest level of access afforded to volunteers and partner contributors. Volunteer maintainers are [nominated](https://github.com/mdn/mdn/issues/new/choose) by our partners or the MDN Web Docs team because they demonstrated a deep understanding of the area of responsibility. These individuals have also demonstrated their comittment to being responisve, reliable, trustworthy and able to interact in a manner that forsters a welcoming and friendly environment. + +Mantainers should: + +- Agree to abide by our [Code of conduct](../../CODE_OF_CONDUCT.md). +- Agree to Mozilla's [Commit Access Requirements](https://www.mozilla.org/en-US/about/governance/policies/commit/requirements/). +- Set up [Two factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) on your GitHub account. +- Have a vouched [Mozillians](https://people.mozilla.org) profile in the [NDA group](https://people.mozilla.org/a/nda/). + +## Owners + +Owners have wide permissions to manage users, teams, maintainer access across repositories in the MDN organisation, maintain repository settings and deploy to production. Owners are currently limited to Mozilla staff and are also bound by all the requirements of the other user levels. In addition to all the responsibilities of the other user levels, owners have the following additional responsibilities: + +- Follow and enforce MDN team norms, including the [code of conduct](CODE_OF_CONDUCT.md) and [Mozilla Policies](https://www.mozilla.org/en-US/about/governance/policies/). +- Follow and contribute to issues and discussions across the MDN organisation. +- Ensure that an issue or pull request gets feedback from one or more members within one week. +- Follow MDN organization policies described in this repo, and lead by example. +- Suggest, document, and implement new policies through the pull request process. +- Add and remove collaborators to repositories as needed. +- [Archive](https://help.github.com/articles/about-archiving-repositories/) or delete unmaintained repositories. +- 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.