diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index e1bd21e51f786fe..a213a75ad22222e 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -2710,7 +2710,7 @@ /en-US/docs/Detecting_device_orientation /en-US/docs/Web/Events/Detecting_device_orientation /en-US/docs/Determining_the_dimensions_of_elements /en-US/docs/Web/API/CSS_Object_Model/Determining_the_dimensions_of_elements /en-US/docs/DeviceAcceleration /en-US/docs/Web/API/DeviceMotionEventAcceleration -/en-US/docs/Devmo:How_to_Help /en-US/docs/MDN/Contribute/Getting_started +/en-US/docs/Devmo:How_to_Help /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/Distribution_options https://extensionworkshop.com/documentation/publish/signing-and-distribution-overview/ /en-US/docs/Distribution_options/Add-ons_for_desktop_apps https://extensionworkshop.com/documentation/publish/distribute-for-desktop-apps/ /en-US/docs/Distribution_options/Add-ons_in_the_enterprise https://extensionworkshop.com/documentation/enterprise/ @@ -3580,7 +3580,7 @@ /en-US/docs/Games/Workflows/Touch_Event_Horizon /en-US/docs/Games/Tutorials/Touch_Event_Horizon /en-US/docs/Games/visual_typescript_game_engine /en-US/docs/Games /en-US/docs/Getting_Started_With_NSS https://firefox-source-docs.mozilla.org/security/nss/index.html -/en-US/docs/Getting_started_on_MDN /en-US/docs/MDN/Contribute/Getting_started +/en-US/docs/Getting_started_on_MDN /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/Glossary/404 /en-US/docs/Web/HTTP/Status/404 /en-US/docs/Glossary/502 /en-US/docs/Web/HTTP/Status/502 /en-US/docs/Glossary/AOM /en-US/docs/Glossary/Accessibility_tree @@ -4006,7 +4006,7 @@ /en-US/docs/How_to_Turn_Off_Form_Autocompletion /en-US/docs/Web/Security/Securing_your_site/Turning_off_form_autocompletion /en-US/docs/How_to_check_the_security_state_of_an_XMLHTTPRequest_over_SSL /en-US/docs/Web/API/XMLHttpRequest /en-US/docs/How_to_create_a_DOM_tree /en-US/docs/Web/API/Document_object_model/How_to_create_a_DOM_tree -/en-US/docs/How_to_start_contributions_to_Mozilla /en-US/docs/MDN/Contribute/Getting_started +/en-US/docs/How_to_start_contributions_to_Mozilla /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/ICC_color_correction_in_Firefox /en-US/docs/Mozilla/Firefox/Releases/3.5/ICC_color_correction_in_Firefox /en-US/docs/IMAP /en-US/docs/Glossary/IMAP /en-US/docs/IPv6 /en-US/docs/Glossary/IPv6 @@ -5394,7 +5394,7 @@ /en-US/docs/MDN/About /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/At_ten/Contributing_to_MDN /en-US/docs/MDN/Contribute /en-US/docs/MDN/Contribute/Code_sample_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide -/en-US/docs/MDN/Contribute/Content /en-US/docs/MDN/Guidelines +/en-US/docs/MDN/Contribute/Content /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Content/Content_blocks /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Content/Custom_macros /en-US/docs/MDN/Writing_guidelines/Page_structures/Commonly-used_macros /en-US/docs/MDN/Contribute/Content/Layout/API_landing_page /en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference @@ -5409,7 +5409,13 @@ /en-US/docs/MDN/Contribute/Does_this_belong /en-US/docs/MDN/Writing_guidelines/What_we_write /en-US/docs/MDN/Contribute/Editor/Live_samples /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/FAQ /en-US/docs/MDN/Contribute -/en-US/docs/MDN/Contribute/Guidelines /en-US/docs/MDN/Guidelines +/en-US/docs/MDN/Contribute/Feedback /en-US/docs/MDN/Community +/en-US/docs/MDN/Contribute/Fixing_MDN_content_bugs /en-US/docs/MDN/Community/MDN_content +/en-US/docs/MDN/Contribute/Getting_started /en-US/docs/MDN/Community/Contributing/Getting_started +/en-US/docs/MDN/Contribute/GitHub_beginners /en-US/docs/MDN/Community/Contributing/Getting_started +/en-US/docs/MDN/Contribute/GitHub_best_practices /en-US/docs/MDN/Community/Issues +/en-US/docs/MDN/Contribute/GitHub_cheatsheet /en-US/docs/MDN/Community/Issues +/en-US/docs/MDN/Contribute/Guidelines /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Guidelines/Best_practices /en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete /en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide @@ -5434,6 +5440,7 @@ /en-US/docs/MDN/Contribute/Guidelines/Style_guide /en-US/docs/MDN/Writing_guidelines/Writing_style_guide /en-US/docs/MDN/Contribute/Guidelines/Video /en-US/docs/MDN/Writing_guidelines/Howto/Images_media /en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide /en-US/docs/MDN/Writing_guidelines/Writing_style_guide +/en-US/docs/MDN/Contribute/Help_beginners /en-US/docs/MDN/Community/Learn_forum /en-US/docs/MDN/Contribute/How_to_document_a_CSS_property /en-US/docs/MDN/Writing_guidelines/Howto/Document_a_CSS_property /en-US/docs/MDN/Contribute/Howto/Compatibility_tables /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Howto/Convert_code_samples_to_be_live /en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples @@ -5443,14 +5450,19 @@ /en-US/docs/MDN/Contribute/Howto/Document_an_HTTP_header /en-US/docs/MDN/Writing_guidelines/Howto/Document_an_HTTP_header /en-US/docs/MDN/Contribute/Howto/Document_web_errors /en-US/docs/MDN/Writing_guidelines/Howto/Document_web_errors /en-US/docs/MDN/Contribute/Howto/How_to_document_a_CSS_property /en-US/docs/MDN/Writing_guidelines/Howto/Document_a_CSS_property +/en-US/docs/MDN/Contribute/Howto/Migrate_external_content_to_MDN /en-US/docs/MDN/Community/Issues/Content_suggestions_feature_proposals /en-US/docs/MDN/Contribute/Howto/Notices /en-US/docs/MDN/Writing_guidelines/Page_structures +/en-US/docs/MDN/Contribute/Howto/Report_a_problem /en-US/docs/MDN/Community/Issues /en-US/docs/MDN/Contribute/Howto/Tag /en-US/docs/MDN/Writing_guidelines/Howto/Tag /en-US/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary /en-US/docs/MDN/Writing_guidelines/Howto/Write_a_new_entry_in_the_Glossary /en-US/docs/MDN/Contribute/Howto/Write_an_API_reference /en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference /en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file /en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file /en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Sidebars /en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars /en-US/docs/MDN/Contribute/Howto/Write_for_SEO /en-US/docs/MDN/Writing_guidelines/Writing_style_guide +/en-US/docs/MDN/Contribute/Localize /en-US/docs/MDN/Community/Contributing/Translated_content /en-US/docs/MDN/Contribute/Markdown_in_MDN /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN +/en-US/docs/MDN/Contribute/Open_source_etiquette /en-US/docs/MDN/Community/Open_source_etiquette +/en-US/docs/MDN/Contribute/Processes/Content_bug_triage /en-US/docs/MDN/Community/Issues/Issue_triage /en-US/docs/MDN/Contribute/Processes/Locating_browser-specific_information /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_version /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_versiosn /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_version /en-US/docs/MDN/Contribute/Sample_app_coding_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide @@ -5484,7 +5496,7 @@ /en-US/docs/MDN/Contribute/Structures/Quicklinks /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Structures/Specification_tables /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Structures/Syntax_sections /en-US/docs/MDN/Writing_guidelines/Page_structures -/en-US/docs/MDN/Contribute/Style_guide /en-US/docs/MDN/Guidelines +/en-US/docs/MDN/Contribute/Style_guide /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Contribute/Style_guide/Compatibility_tables /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Style_guide/Content_blocks /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Contribute/Style_guide/Custom_macros /en-US/docs/MDN/Writing_guidelines/Page_structures/Commonly-used_macros @@ -5493,15 +5505,17 @@ /en-US/docs/MDN/Contribute/Style_guide/Quicklinks /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Style_guide/Specification_tables /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Contribute/Tagging /en-US/docs/MDN/Writing_guidelines/Howto/Tag -/en-US/docs/MDN/Contribute/Tasks /en-US/docs/MDN/Contribute/Getting_started +/en-US/docs/MDN/Contribute/Tasks /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/MDN/Contribute/Tools /en-US/docs/MDN/Tools /en-US/docs/MDN/Contribute/Tools/Document_parameters /en-US/docs/MDN/Tools/Unsupported_GET_API /en-US/docs/MDN/Contribute/Tools/KumaScript /en-US/docs/MDN/Tools/KumaScript /en-US/docs/MDN/Contribute/Tools/KumaScript/Troubleshooting /en-US/docs/MDN/Tools/KumaScript/Troubleshooting /en-US/docs/MDN/Contribute/Tools/Sample_server /en-US/docs/MDN/Tools/Sample_server +/en-US/docs/MDN/Contribute/Where_is_everything /en-US/docs/MDN/Community/Contributing/Our_repositories /en-US/docs/MDN/Doc_status/NSPR https://firefox-source-docs.mozilla.org/nspr/index.html -/en-US/docs/MDN/Feedback /en-US/docs/MDN/Contribute/Feedback -/en-US/docs/MDN/Getting_started /en-US/docs/MDN/Contribute/Getting_started +/en-US/docs/MDN/Feedback /en-US/docs/MDN/Community +/en-US/docs/MDN/Getting_started /en-US/docs/MDN/Community/Contributing/Getting_started +/en-US/docs/MDN/Guidelines /en-US/docs/MDN/Writing_guidelines /en-US/docs/MDN/Guidelines/CSS_style_guide /en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN /en-US/docs/MDN/Guidelines/Code_guidelines /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide /en-US/docs/MDN/Guidelines/Code_guidelines/CSS /en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS @@ -5529,7 +5543,7 @@ /en-US/docs/MDN/MDN_Product_Avisory_Board /en-US/docs/MDN/MDN_Product_Advisory_Board /en-US/docs/MDN/MDN_Product_Avisory_Board/Members /en-US/docs/MDN/MDN_Product_Advisory_Board/Members /en-US/docs/MDN/MDN_Product_Avisory_Board/Membership /en-US/docs/MDN/MDN_Product_Advisory_Board/Membership -/en-US/docs/MDN/Quick_start /en-US/docs/MDN/Contribute/Getting_started +/en-US/docs/MDN/Quick_start /en-US/docs/MDN/Community/Contributing/Getting_started /en-US/docs/MDN/Structures /en-US/docs/MDN/Writing_guidelines/Page_structures /en-US/docs/MDN/Structures/:-ms-input-placeholder_pseudo-class /en-US/docs/Web/CSS/:placeholder-shown /en-US/docs/MDN/Structures/API_references/API_reference_sidebars /en-US/docs/MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index a3eb52754148230..549421ad3aad2fa 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -13071,238 +13071,6 @@ "Mars" ] }, - "MDN/Contribute/Feedback": { - "modified": "2020-12-12T03:21:30.655Z", - "contributors": [ - "sideshowbarker", - "cmiley656", - "chrisdavidmills", - "antinya21", - "SphinxKnight", - "tykfmfocm", - "apselivi", - "jswisher", - "iamshawna1812", - "cheknarin7", - "chinikes", - "tadsan", - "skssagor", - "sohbetxx", - "xsss", - "markwood87", - "ben-turner", - "wbamberg", - "evolmichelle", - "walka69", - "123hpsetupprinters", - "baccarattoyer", - "behnammodi", - "kosta1869", - "Bigbang123", - "anasroubi", - "Sheppy", - "WordConsultant", - "rajkumar0011", - "PareshParmar", - "Greatness", - "fscholz", - "polball", - "hnvgbrt7k", - "nobitaorama", - "Ravi7284", - "MR46DAYAT59", - "Montanacby", - "bartuspan", - "shahin0555", - "anandhv02", - "Ryan_Christian", - "cube1988", - "abogala85", - "seyaka", - "altigere", - "groovecoder", - "openjck", - "teoli", - "kosikfl" - ] - }, - "MDN/Contribute/Fixing_MDN_content_bugs": { - "modified": "2020-10-24T07:21:11.097Z", - "contributors": [ - "chrisdavidmills", - "mdsearle" - ] - }, - "MDN/Contribute/Getting_started": { - "modified": "2020-11-30T06:58:46.025Z", - "contributors": [ - "chrisdavidmills", - "officialsolarstreet11", - "sol07ab", - "SphinxKnight", - "dolunayiki", - "nguyenthanhdanh", - "jhastings", - "jungleboysweed1", - "sideshowbarker", - "k.kant.kumar933", - "sex-doll", - "AdrianaDJ", - "eljawara79", - "mfuji09", - "mercijoel2", - "itsbritime", - "sapnab500", - "jswisher", - "CloudWave_Inc", - "saleva80", - "pergolaimalat", - "oyyunttt", - "pamtentcm", - "aerocityescorts12", - "akshaysv63343", - "Coder-Adam", - "canticleindia", - "RainSlide", - "mrebrahim", - "Iftiahmed2", - "airwawekz", - "ZozoLaFlesh", - "ketoyemek", - "ExE-Boss", - "Backroads", - "Satta-kingdelhi", - "bediroglucom", - "junnydelacruz", - "peterbe", - "shh0884", - "DannyBaobei", - "alattalatta", - "KLIWONJagung", - "Tcw40", - "dcompcoder", - "FIFACOINSZONE", - "TrevTag", - "BohdanLesyk", - "jjjerrmmmy", - "iamvector", - "Akh-rman", - "ariscb10", - "aed1988", - "hercial61", - "Sherina69", - "totoro4sam", - "manalipankaj", - "Sp342h", - "avigdor21", - "Text.8013884634.Me", - "mukhtar-github", - "theanalogueman", - "bminard", - "Tauta2", - "Parziva_1", - "RafeyIqbalRahman", - "bnhassin", - "suravi-afroz", - "wbamberg", - "ruchisin9", - "PerseveranceMbewe", - "0zxo", - "a0989422508", - "Jayman2000", - "avllyx", - "iswanto1", - "Sheppy", - "BranislavGG", - "suterj", - "ptrpov", - "Piyagit", - "artorr", - "tarekanowar", - "varunnagpal12345", - "italktocomputers", - "hphuochung", - "robd4kk", - "KristaOliv", - "Jeremie", - "hidaytrahman", - "LOCAL0325", - "deju233", - "madupenyuburkandungan", - "iaahmed220", - "Fatama-Khanam+880-01741581419", - "jwhitlock", - "Dataware", - "SheehansSyndrome", - "bjohnson", - "amuntner-test", - "NameChangedAsItWasSpam", - "chinju1497", - "saranya", - "faradzhev_t", - "anand01", - "gedex", - "Eric_Anderson", - "mrenty", - "madusa294983", - "hosttor", - "jsx", - "teoli", - "microspeed", - "ebnaysina", - "x2357", - "migmecyber", - "Mrjaydude", - "gaviota", - "RASEl123_ahammed", - "Dnyaneshwar", - "groovecoder", - "80gregistratioin-7", - "vaas786786", - "dvincent", - "Tanzil", - "AmeerAssadi1", - "Umeaboy", - "warner", - "davmagikman", - "aamiryan23", - "udakpakembim", - "klez", - "dayenu", - "eellover", - "q8032482", - "Kathrincolyn", - "Ongkang763", - "mykhael", - "amita", - "MrCreepyGhost", - "apjanke", - "anoopgeorge91", - "samruda", - "tenorioming@yahoo.com", - "herstand", - "TechnoAyan", - "loslch", - "MauricioGil", - "LeoHirsch", - "Chandan1002", - "Vovan", - "kaustavdm", - "Priyanka13" - ] - }, - "MDN/Contribute/GitHub_best_practices": { - "modified": "2020-10-21T05:23:39.270Z", - "contributors": [ - "chrisdavidmills" - ] - }, - "MDN/Contribute/Help_beginners": { - "modified": "2020-10-09T11:27:17.278Z", - "contributors": [ - "chrisdavidmills" - ] - }, "MDN/Contribute/Howto": { "modified": "2020-12-14T11:30:11.910Z", "contributors": [ @@ -13326,24 +13094,6 @@ "jswisher" ] }, - "MDN/Contribute/Howto/Migrate_external_content_to_MDN": { - "modified": "2019-07-15T08:26:43.504Z", - "contributors": [ - "Sheppy", - "wbamberg", - "jswisher", - "chrisdavidmills" - ] - }, - "MDN/Contribute/Howto/Report_a_problem": { - "modified": "2019-12-31T16:24:19.538Z", - "contributors": [ - "peterbe", - "jswisher", - "wbamberg", - "hamasaki" - ] - }, "MDN/Contribute/Howto/Update_the_CSS_JSON_DB": { "modified": "2019-03-23T22:47:20.816Z", "contributors": [ @@ -13356,22 +13106,6 @@ "teoli" ] }, - "MDN/Contribute/Localize": { - "modified": "2020-12-12T05:45:10.381Z", - "contributors": [ - "SphinxKnight", - "irvinfly", - "chrisdavidmills", - "wbamberg", - "pascalchevrel", - "jwhitlock", - "jswisher", - "mstanke", - "Sheppy", - "ethertank", - "FredB" - ] - }, "MDN/Contribute/Processes": { "modified": "2020-09-30T15:17:09.733Z", "contributors": [ @@ -13447,15 +13181,6 @@ "jswisher" ] }, - "MDN/Guidelines": { - "modified": "2020-09-30T15:27:11.839Z", - "contributors": [ - "chrisdavidmills", - "wbamberg", - "jswisher", - "Sheppy" - ] - }, "MDN/Guidelines/Code_guidelines": { "modified": "2020-09-30T15:27:12.089Z", "contributors": [ diff --git a/files/en-us/mdn/community/issues/index.md b/files/en-us/mdn/community/issues/index.md index 2adddc3022e1aea..21546a7d83e2e26 100644 --- a/files/en-us/mdn/community/issues/index.md +++ b/files/en-us/mdn/community/issues/index.md @@ -73,15 +73,13 @@ All repositories have an issue tracker, where you can find tasks to help contrib 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. +Once you've found an issue you'd like to work on, make 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)_ +Most issues need some investigation before work can start, if you need to ask questions 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). 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). +Fork and branch the repository, do your work and open a [pull request](../pull_requests/index.md). _(more stuff)_ diff --git a/files/en-us/mdn/community/issues/issue_triage/index.md b/files/en-us/mdn/community/issues/issue_triage/index.md index bbc4ef75339dfb8..b9e202c651957c0 100644 --- a/files/en-us/mdn/community/issues/issue_triage/index.md +++ b/files/en-us/mdn/community/issues/issue_triage/index.md @@ -8,4 +8,133 @@ tags: - governance --- -_(see meta docs)_ +This document looks at the process for triaging content bugs and getting them ready for contributors to effectively work on. + +## Reporting and working on bugs + +Anyone can report a content bug by writing an issue at using the "Content bug" issue template, or by using the "Report a problem with this content on GitHub" link at the bottom of each MDN page. + +Once reported, content bugs are listed at , and are designed to be done by individuals with minimal process requirements. Anyone is welcome to work on a content bug, using the process outlined at [Fixing MDN content bugs](/en-US/docs/MDN/Contribute/Fixing_MDN_content_bugs). + +## Overall triage process + +At a high level, the process for triage looks like so: + +Triage preparation: + +- Decide on triagers — Who will do the regular triage? +- Set initial labels — As soon as a new bug comes in, give it the "needs-triage" label, to signify that it needs to be triaged (this should happen automatically), plus a "Content:" label to signify what topic area it is in, e.g. "Content:HTML". Anyone can do this as they spot bugs coming in, but the MDN core team will keep an active eye on this. +- Set aside triage time — set out a regular 30-minute slot in which to do the triage, each week. + +Triage for each issue: + +- Checklist — run through checklist to see if it is ready to triage. +- Set priority measure — according to priority rules. +- Provide further information to help other contributors start working on bugs more easily. +- Set other labels — there are other labels to set, to help people to choose issues to work on. + +Check through old bugs — look at existing bugs, and see if there are any that are stalled, or need closing, etc. + +## Triage preparation + +### Decide on triagers + +We need an assigned triager to regularly triage bugs coming in on each MDN content area. We currently have the following triagers assigned: + +- Accessibility — Eric Bailey? +- CSS — Rachel Andrew +- DevTools — Hamish Willee +- HTML — Rachel Andrew +- HTTP — Florian Scholz +- JS — Florian Scholz +- Learn — Chris Mills +- Learn:CSS — Rachel Andrew +- Learn:Express / Learn:Django — Hamish Willee +- Media — Ruth John +- Other — Ruth John +- SVG — André Jaenisch +- WebAPI — Ruth John +- WebExt — Caitlin/WebExt team + +### Set initial labels + +As soon as a new issue is filed, the MDN core team, and anyone else who wishes to help, will add the following labels to that issue: + +- `needs-triage` — signals that this issue needs a proper triage, to get it ready to work on (this should happen automatically). +- `Content:` — specifies the content topic this issue relates to, e.g. `Content:HTML` or `Content:CSS`. This needed for the triagers to be able to find the issues in their specific areas. +- `l10n-fr`, `l10n-zh`, `l10n-ja` — specifies that the issue filed concerns an active non-en-US locale. The teams for those locales will pick these issues up and triage them. + +### Set aside triage time + +Triagers don't need to be actively triaging bugs all the time. Instead, they should set out a 30-minute slot in which to triage the bugs in their area of responsibility, each week. + +This doesn't have to be done as part of a synchronous meeting, or even at the same time as everyone else, but it should be done regularly, say once per week, to make sure that the backlog of untriaged bugs doesn't get too high. + +## Triage process for each issue + +### Checklist to determine if we have enough information + +For each bug, run through the following checklist to make sure the issue contains enough information for someone to start working on the bug. + +Does the issue contain: + +- The MDN URL where the problem has been found. +- The URL of any example page or repo related to the bug, if appropriate. +- The specific heading on the MDN page where the problem can be found (if needed to find it). +- A clear description of what the problem is. + +If this information is not present, then the triager should ask the submitter of the issue to provide these details, and not continue triaging the issue until those details are provided. + +### Set priority measure + +For each bug, set a priority measure label to help people who want to work on the most important issues or areas (rather than the topics they are interested in). + +The levels of priority are: + +- `P0` — A critical issue on any MDN doc. +- `P1` — A major issue on a Tier 1 MDN doc. +- `P2` — A minor issue on a Tier 1 MDN doc. +- `P3` — A major issue on a Tier 2 MDN doc. +- `P4` — A minor issue on a Tier 2 MDN doc. + +Definitions: + +- Critical issue — Something that could damage MDN's reputation severely and/or harm users, which we need to fix as soon as possible, regardless of where it appears on the site. Examples include code examples that if used in production could create a severe security issue, undesirable content such as malware, profanity, pornography, hate speech, or other undesirable content, or links to such content. +- Major issue — Something that could severely affect a page's usefulness, for example a significant amount of out-of-date information, a complex and important code example that doesn't work, a significant amount of prose that is badly written and hard to understand, a large number of broken links, etc. +- Minor issue — something that doesn't look great but does not affect learning, or only has a minor effect on learning. Examples — Typos, bad grammar, a broken link, a small amount of out-of-date information or badly-written prose, a small code snippet that doesn't work. + +Generally speaking, critical issues should be fixed immediately, and would probably be handled by MDN staff/peers. And Tier 1 issues are more important than Tier 2 issues. Folks that are interested in tackling the highest priority MDN issues should always tackle Tier 0 issues if any are available, before moving on to Tier 1 then Tier 2 issues. + +> **Note:** For definitions of Tier 1 and Tier 2, see the [MDN documentation priority list](https://mdn-contributor-docs.mozilla.org/legacy/documentation-priorities/). + +### Provide further information + +It is really useful for other contributors to provide them with further information to help them fix issues; we'd like to recommend that triaging each bug involves a time-box of up to 5 minutes in which the triager quickly describes some steps to take to fix the bug, to help the person who eventually tries to fix it. + +For example: + +```plain +To whoever fixes this issue, it looks like the following is needed: + +* Update the first paragraph below heading X to correct the problem with Y +* Add a description of X +* Update the compatibility data at Link-X +``` + +### Set other labels + +Next, set other labels as appropriate: + +- `10 minute task`, `30 minute task`, `1 hour task`, `multiple hour task` — Some people like to search for bugs based on how much time they've got to contribute, so we like to give a rough measure to allow people to choose. We appreciate that this is hard to estimate, and that different people will fix bugs at different speeds, but this is only supposed to be a rough measure. When setting it, think about how much time you think someone with a moderate-to-good amount of knowledge in the subject area would take to fix it. +- `good first issue` — if the fix for the issue is really simple, and it would be a good practice issue for a newcomer just getting used to the system, mark it with this label. +- `help wanted` — this seems to be a very popular label for people to use to search for things to do on open source projects, so we set this as a matter of course on successfully-triaged bugs. +- `broken-link-internal`, `broken-link-external` — use these if the issue involves a link to a non-existent internal page, or a broken external link. +- Once the triage process is completed, **don't forget to remove the `needs-triage label`.** + +## Check through old issues + +At the end of your triage session, have a look through the older existing triaged issues in your topic area, and check to make sure none of the issues are being unnecessarily stalled or clogged up: + +- Check assigned issues that are still open to see if the assignee is making progress. If they have done nothing after a week of being assigned, ask them if they still have to work on the issue. If another week passes and they have still done nothing, unassign them and say that you are opening this up again for others to take. +- If a PR has been issued to fix the issue but it has not been reviewed for a week, give the reviewer a gentle ping to ask if they can get to it. +- If a PR is waiting on review comments to be addressed after a week, then ask the submitter if they can respond to their review. If another week goes by, either fix the review comments yourself if you have time, or close the PR if not. diff --git a/files/en-us/mdn/contribute/feedback/index.md b/files/en-us/mdn/contribute/feedback/index.md deleted file mode 100644 index 1e72301d2c6b629..000000000000000 --- a/files/en-us/mdn/contribute/feedback/index.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Send feedback about MDN Web Docs -slug: MDN/Contribute/Feedback -tags: - - Documentation - - Guide - - MDN - - MDN Meta ---- -{{MDNSidebar}} - -Welcome to MDN Web Docs! If you have suggestions for, or are having problems using the MDN Web Docs, this is the right place to be. The very fact that you're interested in offering feedback makes you even more a part of the Mozilla community, and we thank you in advance for your interest. - -You have several options for offering your insight; this article will help you do so. - -## Update the documentation - -First of all, if you've seen a problem with the documentation, you should always feel free to correct it yourself. Start by reading about the [specific steps for getting set up to make contributions](https://github.com/mdn/content/#making-contributions). - -The sources for the documentation here are [stored in GitHub](https://github.com/mdn/content/), and curated by a team of volunteers and paid staff, so don't be shy — your grammar doesn't have to be perfect. We'll review your changes and help you fix any mistakes; no harm done! - -For more information about contributing to MDN documentation, see: - -- [Getting started](/en-US/docs/MDN/Contribute/Getting_started), for more details on how to begin. -- [Contributing to MDN](/en-US/docs/MDN/Contribute), for ideas of specific tasks you can do to help. - -## Join the conversation - -Talk to us! There are a few ways to get in touch with other people who work on MDN content. - -### (Synchronous) Chat - -We use [Matrix](https://wiki.mozilla.org/Matrix) to converse about MDN and its content. You can join in the conversation! - -[MDN Web Docs](https://chat.mozilla.org/#/room/#mdn:mozilla.org) - -This room is for general discussion of MDN: using the site, reading content on the site, and contributing to the site's content. If you have questions or comments about article content, new articles you'd like to see or create, or just want to talk with the writing team, this is the place to be. - -### (Asynchronous) Discussions - -Longer-term discussions happen on our [MDN discussion forum](https://discourse.mozilla.org/c/mdn/236). You can post to the forum via email to [mdn@mozilla-community.org](mailto://mdn@mozilla-community.org). If you join the forum, you can choose to have notifications about discussions sent to you via email as well. - -## Report an issue - -### Documentation issues - -If you see a problem in the documentation and can't fix it yourself for any reason, you can [report the issue](https://github.com/mdn/content/issues/new/choose)! For some problems of translation, you can [report to translated content](https://github.com/mdn/translated-content/issues/new/choose "Report a translation problem."). You can use this form for any documentation issue at all, for example: - -- a simple correction -- a request for an entirely new piece of content -- reporting inappropriate content (including spam and misplaced translations) - -As mentioned before, we invite you to contribute the changes yourself, but this option is available for you as well. - -### Site issues - -If you encounter problems with the MDN website, or have ideas for new features for the site, you can [submit a ticket to the MDN development team](https://github.com/mdn/yari/issues). diff --git a/files/en-us/mdn/contribute/fixing_mdn_content_bugs/index.md b/files/en-us/mdn/contribute/fixing_mdn_content_bugs/index.md deleted file mode 100644 index 12eeed2e9da41ec..000000000000000 --- a/files/en-us/mdn/contribute/fixing_mdn_content_bugs/index.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Fixing MDN content bugs -slug: MDN/Contribute/Fixing_MDN_content_bugs -tags: - - Bugs - - Contribute - - MDN ---- -{{MDNSidebar}} - -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/contribute/getting_started/index.md b/files/en-us/mdn/contribute/getting_started/index.md deleted file mode 100644 index 287f792a784f238..000000000000000 --- a/files/en-us/mdn/contribute/getting_started/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Getting started on MDN -slug: MDN/Contribute/Getting_started -tags: - - Documentation - - Getting Started - - Guide - - MDN - - MDN Project - - New Contributors ---- -{{MDNSidebar}} - -We are an open community of developers 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. - -Every part of MDN (docs, demos, and the site itself) is created by an open community of developers. Please, join us! - -## 4 simple steps to MDN - -MDN is an open-source resource where **anyone** can add and edit content. You don't need to be a programmer or know a lot about technologies. There are plenty of things that need to be done, from the simple (proofreading and correcting typos) to the complex (writing API documentation). - -Contributing is easy and safe. Even if you make a mistake, it's easily fixed. Even if you don't know exactly how things should look, or your grammar isn't all that good, don't worry about it! We have a team of people whose job is to make sure that MDN's contents are as good as possible. Someone will be along to make sure your work is tidy and well-written. Share what you know and follow your strengths. - -### Step 1: Create a GitHub account - -To begin your contributions to MDN, you need to [create a GitHub account](https://github.com/mdn/content/#setup). - -### Step 2: Pick a task to complete - -Now that you are logged in, read the descriptions of the different task types available on the [main Contribute page](/en-US/docs/MDN/Contribute), and decide which one most appeals to you. You can pick any task you like and begin your contribution. - -### Step 3: Do the task - -Once you've decided what kind of task you want to do, find a specific page, code example, etc. to work on, and just do it! - -### Step 4: Ask for help - -If you are not sure what to do at any point, then you are more than welcome to ask for help. There are a few different help options: - -- If you want to talk to us synchronously and ask questions about MDN itself, join the discussion on the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix). -- You can also drop us an email at . -- 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. - -Don't worry about doing it perfectly; other MDN contributors are here to help fix errors that slip through. - -## Useful complete beginner's guides - -We expect contributors to MDN to have a certain amount of prerequisite knowledge -before they start working on the content. If you are new to the following -topics, we'd advise you to look at the provided links to help you get up to -speed: - -- Web technologies: If you are new to HTML, CSS, JavaScript, etc., check out our [Learn web development](/en-US/docs/Learn) tutorials. -- Open source: If you've never contributed to an open-source project before, have a read of [Basic etiquette for open source projects](/en-US/docs/MDN/Contribute/Open_source_etiquette). -- Git and GitHub: If you are unfamiliar with these tools, [GitHub for complete beginners](/en-US/docs/MDN/Contribute/GitHub_beginners) will get you started. -- MDN's repo structures: If you are not sure what repos to edit to make changes to the different parts of MDN's content, [Where is everything on MDN?](/en-US/docs/MDN/Contribute/Where_is_everything) will point you towards the correct places. diff --git a/files/en-us/mdn/contribute/github_beginners/branch-button-new-branch.png b/files/en-us/mdn/contribute/github_beginners/branch-button-new-branch.png deleted file mode 100644 index cfd7bc61de6b340..000000000000000 Binary files a/files/en-us/mdn/contribute/github_beginners/branch-button-new-branch.png and /dev/null differ diff --git a/files/en-us/mdn/contribute/github_beginners/branch-button.png b/files/en-us/mdn/contribute/github_beginners/branch-button.png deleted file mode 100644 index a19007b3d997eb2..000000000000000 Binary files a/files/en-us/mdn/contribute/github_beginners/branch-button.png and /dev/null differ diff --git a/files/en-us/mdn/contribute/github_beginners/branch-menu.png b/files/en-us/mdn/contribute/github_beginners/branch-menu.png deleted file mode 100644 index a2893e28693f8db..000000000000000 Binary files a/files/en-us/mdn/contribute/github_beginners/branch-menu.png and /dev/null differ diff --git a/files/en-us/mdn/contribute/github_beginners/code-popup.png b/files/en-us/mdn/contribute/github_beginners/code-popup.png deleted file mode 100644 index 233c741bec18647..000000000000000 Binary files a/files/en-us/mdn/contribute/github_beginners/code-popup.png and /dev/null differ diff --git a/files/en-us/mdn/contribute/github_beginners/compare-and-pull-request.png b/files/en-us/mdn/contribute/github_beginners/compare-and-pull-request.png deleted file mode 100644 index f4cb639948511ed..000000000000000 Binary files a/files/en-us/mdn/contribute/github_beginners/compare-and-pull-request.png and /dev/null differ diff --git a/files/en-us/mdn/contribute/github_beginners/fork-button.png b/files/en-us/mdn/contribute/github_beginners/fork-button.png deleted file mode 100644 index 91ab8dc24e78c31..000000000000000 Binary files a/files/en-us/mdn/contribute/github_beginners/fork-button.png and /dev/null differ diff --git a/files/en-us/mdn/contribute/github_beginners/index.md b/files/en-us/mdn/contribute/github_beginners/index.md deleted file mode 100644 index 9f84209e1d3f53c..000000000000000 --- a/files/en-us/mdn/contribute/github_beginners/index.md +++ /dev/null @@ -1,432 +0,0 @@ ---- -title: GitHub for complete beginners -slug: MDN/Contribute/GitHub_beginners -tags: - - Best practices - - Community - - GitHub - - MDN - - Beginners ---- -{{MDNSidebar}} - -[Git](https://git-scm.com/) and [GitHub](https://github.com/) are challenging tools to learn and master, but with a few simple commands and some good advice, you should be able to do enough to start contributing to MDN without too much trouble. The aim of this article is not to help you master Git or GitHub, but to give you just enough to be productive with it at a basic level and contribute to MDN. - -If you are familiar with Git/GitHub basics already, you probably won't learn anything new here, but you may still find this article useful as a reference. There is a [GitHub cheatsheet](/en-US/docs/MDN/Contribute/GitHub_cheatsheet) available too, with just the commands and none of the long explanations. - -## Essential concepts - -The following are essential concepts that you must be familiar with to get the most out of Git and GitHub. - -- Git is a _version control system_ tool — an essential class of tools in any development workflow. It allows a group of developers to work on the same code base without getting in each other's way, stores the code base safely in a remote location, allows developers to roll the code back to previous states if required, and more. -- GitHub is a web application that provides useful tools on top of Git for working with stored codebases, as well as server space to store the codebases. Its functions are similar to those of other applications, such as [GitLab](https://about.gitlab.com/) or [Bitbucket](https://bitbucket.org/). -- Each codebase is stored in a container called a _repository_, or _repo_. -- Making a change to a repository minimally involves: - - - Creating your own copy of that repo (called a _fork_). - - Creating a different version of the code in your fork of the repo (called a _branch_) and adding your changes to that alternative version. - - Proposing to make that change in the original copy of the repo via a _pull request_. You'll be learning all of these steps in this guide. - -## Assumptions made by this article - -This article assumes that: - -- You are already comfortable with using the command line/terminal. If you are new to the command line, have a read of our [Command line crash course](/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line). -- You are working on a system that understands standard Unix-style command line commands. macOS/Linux have this available out of the box; [Windows isn't quite as simple](/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Command_line#windows) in this regard, but there are useful applications that emulate this functionality on Windows, such as Gitbash. -- You'll be using the command line to interact with Git/GitHub. There are a number of GUI tools available for Git and GitHub, but they won't work with this guide. - -## Initial setup - -Before you get started with working on any particular repo, follow these steps: - -1. Install Git on your computer. Go to the [Git downloads page](https://git-scm.com/downloads), download the latest version for your computer, and install it. If you are a Windows user, you should also install the [Git for Windows](https://gitforwindows.org/) package, which includes Gitbash. -2. While you are at it, install the other required dependencies for working locally with MDN — [Node.js](https://nodejs.org/en/download/) and [yarn](https://classic.yarnpkg.com/en/docs/install). - - 1. Install Node.js by following the above link and downloading and installing the latest version for your computer. - 2. Once you've installed Node.js, install Yarn by running `npm install --global yarn`. - -3. Create a separate directory somewhere on your computer to store all of your Git repos in, which is easy to find and navigate to on the command line. A directory called mdn-git inside your home/user directory would be suitable. -4. [Sign up for a GitHub account](https://github.com/join) if you don't already have one. You'll need this to contribute to MDN's repos. - -### Setting up SSH authentication on GitHub - -At this point you need to set up an SSH key on your GitHub account. This is basically a security mechanism that identifies you to GitHub, and means that you don't have to authenticate each time you use GitHub services. - -GitHub has created a useful guide to setting this up — see the starting point at [Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). Follow each of the steps here to get set up with SSH on GitHub. - -If you don't do this, you'll still be able to contribute to MDN, but you'll have to enter your username and password every time you interact with GitHub (e.g. whenever you submit a pull request, as seen below). - -## Setting up to work on a specific repo - -There are a number of different repos you may have to update as you work on different MDN tasks (see [Where is everything on MDN? A guide to our repos](/en-US/docs/MDN/Contribute/Where_is_everything)), but there are a number of setup steps you should follow on every repo you work on, to make things easier and more consistent. - -### Forking and cloning - -_Forking_ and _cloning_ are two terms you'll come across often in the world of Git: - -- Forking means creating your own copy of a repo on GitHub. -- Cloning means making a local copy of a repo for you to work on (i.e. on your local hard drive). - -It is possible to do the two things separately, but in practice you will nearly always do them together when contributing to other people's projects. You should first make a fork of each repo you want to work on. This is required for you to submit change requests to the main version of the repo (we'll learn how to create a pull request later on). Due to security reasons, you can't submit changes directly to the main version of the repo. So to submit changes, first fork the main repo, then push the changes to your fork, and then create a pull request to get the changes from your fork merged into the main repo. - -Let's fork right now; you'll definitely be contributing to this repo at some point. Follow these steps: - -1. Locate the Fork button at the top-right-hand corner of the content repo's page, and press it: - - ![Button labeled fork, with the number 609 next to it](fork-button.png) - -2. A modal window will appear, asking you where you want to fork the repo to. Select your personal GitHub account. - - A message will appear saying something like "Forking mdn/content. It should only take a few seconds." Once GitHub has finished forking, your browser should redirect to the page for the new fork. As an example, my fork of is available at . - -Now you've forked the repo, it is time to clone your fork locally. To do this: - -1. Go to your fork's page on github.com (e.g. `https://github.com//content`). -2. Press the green "Code" button at the top of the files list. Something similar to the following popup should appear as a result: - - ![Popup window showing a clone URL along with options to open with GitHub Desktop and download zip](code-popup.png) - -3. If you set up SSH authentication as instructed above, click the "SSH" tab and copy the `git@github.com:/content.git` URL from the text field in the box. If you didn't set up SSH authentication, copy the URL from the text field on the "HTTPS" tab instead, which should look like this: `https://github.com//content.git`. -4. Now open up the command line on your computer, and navigate into the directory you set up earlier to store your local git repo clones in using the cd command, e.g. - - ```bash - cd git - ``` - -5. Clone your fork by entering a command with the following form: - - ```bash - git clone the-url-you-copied - ``` - - So for example my cloning command looked like this: - - ```bash - git clone git@github.com:chrisdavidmills/content.git - ``` - -You should now find a content directory inside your git directory, containing the contents of the repo. - -### Setting up a remote to point to the main version of the repo - -One last thing to do before moving on is set up a _remote_ to point to the main version of the repo, e.g. in the case of our example. A remote is basically a pointer to a specific remote repo location on GitHub, and is most commonly used to update your local clone so it is up-to-date with the latest main repo, as we'll see below. - -Setting up a remote is done with the `git remote add` command, which looks like this: - -```bash -git remote add remote-name repo-you-want-to-point-to -``` - -- _remote-name_ is a name that you decide on, which is used to refer to the remote later on. It is good to stick to a consistent name for remotes across different repos that have the same purpose, so the same remote name will do the same thing everywhere, and you are less likely to get confused. So for example, the main version of the repo that you forked your version from is often called the "upstream repo", therefore people often use "upstream" as the name of the remote upstream location. I usually call my upstream remotes "mozilla", to signify that they point to Mozilla's main copy of the repo. -- _repo-you-want-to-point-to_ is the SSH (or HTTPS) URL of the repo you want to point to, retrieved in the same way as we did when we were cloning our fork earlier. - -So, to add your remote: - -1. Go to the github.com page for the main version of the repo ( in this example) and retrieve the SSH or HTTPS URL as appropriate, from the "Code" popup. -2. In your command line, `cd` into your content directory: - - ```bash - cd content - ``` - -3. Now run a command along the following lines, replacing _remote-name_ and _repo-you-want-to-point-to_ as appropriate: - - ```bash - git remote add remote-name repo-you-want-to-point-to - ``` - - So for example, I used the SSH URL and called my remote "mozilla": - - ```bash - git remote add mozilla git@github.com:mdn/content.git - ``` - -Your remote should now be set up. You can verify it by running the command `git remote -v` in your terminal, which outputs a list of your remote names and where they point to. You should see something a bit like this: - -```plain -mozilla git@github.com:mdn/content.git (fetch) -mozilla git@github.com:mdn/content.git (push) -origin git@github.com:chrisdavidmills/content.git (fetch) -origin git@github.com:chrisdavidmills/content.git (push) -``` - -## Preparing to make a change to the repo - -Now you've got your local fork clone all set up to work with, there is a set of commands you should get in the habit of running before you attempt to make any new changes. - -### Switch to the main branch - -Each repo has a number of different branches, which are basically different versions of the codebase inside the same repo. The idea is that for each change to a codebase, you make the change on a separate branch and test it there first, before then pushing the changes to the main copy of the code. - -The main branch of the content repo is called "main" (it might be called something else like "master" in other repos, and if so you'll have to update the name of it in all commands shown below). You'll be on this branch by default if you've just cloned the repo, but if you've already done some work you'll likely be on a different branch. -Make sure you run the following to switch to the main branch before doing anything else: - -```bash -git switch main -``` - -> **Note:** In other tutorials you may have seen `git checkout` used to change branches in a repo. That works fine most of the time, but can sometimes have unintended side-effects, therefore in this tutorial we are recommending the newer `git switch` command, which is designed purely for switching branches and has less chance of going wrong. If you are interested in how these commands are related, and the differences between them, [Highlights from Git 2.23 > Experimental alternatives for git checkout](https://github.blog/2019-08-16-highlights-from-git-2-23/#experimental-alternatives-for-git-checkout) provides a good summary. - -### Update your main branch - -Next up, you should update your main branch so that it contains the same content as the main branch of the main repo. The content repo is updated many times every day by a large number of contributors, so if you don't do this, your version will get out-of-date, and this will cause problems when you try to submit your updates. This is where your remote will come in handy! - -To update your repo: - -1. First fetch the updated contents of your remote with the following command: - - ```bash - git fetch remote-name - ``` - - So for example: - - ```bash - git fetch mozilla - ``` - -2. Next, replace the contents of your main branch with the remote repo's main branch. There are many different ways you could do this, but I tend to use the `rebase` command, like this: - - ```bash - git rebase remote-name/main-branch-name - ``` - - So for example: - - ```bash - git rebase mozilla/main - ``` - -3. Finally, push those changes up to the remote version of your fork using: - - ```bash - git push - ``` - -You'll know if your updates worked properly by looking at the github.com page for your fork (i.e. mine is ). It should say something like "This branch is even with mdn:main." somewhere near the top. If it says your main branch is behind mdn:main by a number of commits, then you'll need to try it again, or [troubleshoot](#troubleshooting). - -### Create a new branch to do your work in - -Once you've got your main branch up to date in your fork, you must always create a new branch to make a change in. You should _never_ do your work in the main branch and submit it from there — it can get messy very quickly, trust us. It is a lot cleaner and less error-prone to do all work in separate branches. - -To create a new branch: - -1. Go to your fork's page on github.com (i.e. mine is ) and find the branch button at the top left-hand corner of the file list, which should say "main" on it: - - ![Button labeled main](branch-button.png) - -2. Click on this, and you'll be presented with a list of branches and a text field that says "Find or create a branch…": - - ![menu showing list of branch names with a text box labeled find or create a branch](branch-menu.png) - -3. If you enter part of an existing branch name in the text field, it will filter the list of branches against that string, allowing you to search for existing branches easily. However, we want to create a new branch. Enter a branch name that doesn't already exist (try something like test-branch) and the display will change to give you a button labelled "Create branch: test-branch from 'main'": - - ![menu showing a new branch name test-branch entered into a text box, with a create branch button below it](new-branch.png) - -4. Once you are happy with your branch name, click on this button, and the display will update to show the branch name in the branch button: - - ![Button labeled test-branch](branch-button-new-branch.png) - -That's it! You have now created a new branch to do your work in. This branch is identical to the main branch's state at the time that you created it. A good starting point to do our work from. - -Tips: - -- Make sure that you always update your main branch to be in sync with the mozilla main branch, as discussed in the previous section, before creating a new branch. -- Make sure that you always create your new branch based on main, and not some other branch. To do this, make sure that the branch button shows "main" before starting the process. If you don't, your new branch will likely be really out of date, which will create content problems. - -### Get your branch locally and switch to it - -The previous section taught you how to create a new branch in your fork, but it currently only exists in your remote version of the fork. To work on it, you need to get it into your local version. - -To do this, go back to your terminal and, making sure you are inside the repo directory you are working with (`content` for this example): - -1. Pull remote changes to your local clone by running the command `git pull` -2. You should get a message along the lines of `* [new branch] test-branch -> origin/test-branch` -3. To switch to your branch (meaning change over from "main", to work in that branch instead) run the command `git switch test-branch` - -If you were successful, git should tell you something like this: - -```plain -Branch 'test-branch' set up to track remote branch 'test-branch' from 'origin'. -Switched to a new branch 'test-branch' -``` - -Note that you can check the status of your repo, including what branch you are on, at any time by running the command `git status`. Try this now, and git should tell you something like this: - -```plain -On branch test-branch -Your branch is up to date with 'origin/test-branch'. - -nothing to commit, working tree clean -``` - -This sounds about right. We are on the "test-branch" branch, and we've made no changes yet. - -## Adding, committing, and pushing changes - -At this point you are ready to make changes to the repo you are working on — to fix a bug on MDN or whatever it is that you are doing. We will mostly skip this part, as that's not the point of the tutorial. If you want to fix a real problem on MDN, go and choose a bug to fix from our [content issues list](https://github.com/mdn/content/issues/), or read [Contributing to MDN](/en-US/docs/MDN/Contribute) for more guidance. - -If you just want to follow along with this tutorial for example's sake, let's do something simple. - -1. Go into the `content/README.md` file, and add a single letter into the top heading of the README. -2. Now go back to your command line and enter the `git status` command again. This time git should tell you something like this: - - ```plain - Your branch is up to date with 'origin/test-branch'. - - Changes not staged for commit: - (use "git add ..." to update what will be committed) - (use "git restore ..." to discard changes in working directory) - modified: README.md - - no changes added to commit (use "git add" and/or "git commit -a") - ``` - -3. So at this point it is telling you what files you have modified. The next stage is to "add" them, which means add them to a list of files that you want to commit to push up to the remote fork. To add this file to the commit list, type the following: - - ```bash - git add README.md - ``` - - > **Note:** `README.md` is the path to the file you have changed, not just its name. If it were inside a subdirectory, you'd have to write the full path to the file. - -4. If you run `git status` again, you'll now see this: - - ```plain - On branch test-branch - Your branch is up to date with 'origin/test-branch'. - - Changes to be committed: - (use "git restore --staged ..." to unstage) - modified: README.md - ``` - -5. Git is telling us that `README.md` is now in our commit list. To include all the files in the commit list in a commit (a single set of changes that we will later try to send to the main branch), enter the following (the `-m` option is short for message"): - - ```bash - git commit -m 'my first commit' - ``` - - Git will tell you this: - - ```plain - [test-branch 44b207ef6] my first commit - 1 file changed, 1 insertion(+), 1 deletion(-) - ``` - - To show that it has registered that you've made a commit. - -6. Run `git status` again, and you'll get this information: - - ```plain - On branch test-branch - Your branch is ahead of 'origin/test-branch' by 1 commit. - (use "git push" to publish your local commits) - - nothing to commit, working tree clean - ``` - -The information readout has basically reset — it is telling us that there are no changes to commit, because we've now sent our previous change into the system as a commit. The key difference from before is the line "Your branch is ahead of 'origin/test-branch' by 1 commit." — our local version of the "test-branch" branch is now ahead of the remote version of "test-branch" by one commit — in other words, we've made a change locally that the remote branch doesn't have. - -Let's send our local change to the remote branch. You can do this by running the command `git push` — try this now. If there are no errors, you should get a readout like this: - -```plain -Enumerating objects: 5, done. -Counting objects: 100% (5/5), done. -Delta compression using up to 8 threads -Compressing objects: 100% (3/3), done. -Writing objects: 100% (3/3), 292 bytes | 292.00 KiB/s, done. -Total 3 (delta 2), reused 0 (delta 0) -remote: Resolving deltas: 100% (2/2), completed with 2 local objects. -To github.com:chrisdavidmills/content.git - 77215e31e..44b207ef6 test-branch -> test-branch -``` - -## Creating a pull request - -At this point, go back to your remote fork's github.com page. You should see a message along the lines of "This branch is 1 commit ahead of mdn:main. " meaning that our fork's content has a content change (commit) in it that mozilla's "main" branch doesn't have. - -1. To send our change up to the main copy of the repo, we need to create a pull request. This can be easily done using the "Compare & pull request" button that you should see up the top of the files list, once the branch has had a change pushed to it. - - ![Banner with text test branch had recent pushes, and a button labeled compare and pull request](compare-and-pull-request.png) - - Press this button, and you should get a new screen appearing along these lines: - - ![open pull request form, which includes text fields for title and description](open-pull-request.png) - - > **Warning:** Only follow the rest of these steps if you have a real change to make to the repo! Please do not actually submit test PRs to our repos. - -2. At this point, enter a useful title and description for your PR, saying exactly what it changed, why this is a good thing, and what related issue it fixed, if appropriate. Specifically, include a line saying `Fixes issue-url`. GitHub automatically renders this as a link to the issue number, e.g. `Fixes #1234` and, in addition, automatically closes the related issue once the pull request is merged. -3. Once you are ready to send your pull request, click the "Create pull request" button. This will cause your pull request (PR) to appear in the repo's [Pull requests list](https://github.com/mdn/content/pulls), where it'll be reviewed by our review teams, and hopefully merged into the main codebase. - - If the review team has changes they want you to make, they'll tell you in comments in the pull request thread (you should receive an email notification to tell you this). - -4. If you want to make further changes to the same pull request you've already submitted, you can do so by making more commits on the same local branch and then pushing them as explained previously. There is no need to create a completely new pull request. **Just make sure you are making them on the same branch as before**. - -## Troubleshooting - -The above tutorial is aimed at providing you with the basics of git and GitHub that you'll need to contribute to GitHub repos at a basic level. We hope it was helpful! We'd also like to discuss the fact that, despite being the industry standard version control system for the web industry, Git has a kind of mythical/legendary reputation as a painfully difficult tool to learn and use. - -We're not sure this is entirely fair. Git has a lot of commands that are sometimes fairly cryptic in their use, and does take a long time to master. It is also fair to say that if you forget some of the commands or do things in the wrong order you can find yourself in some interesting messes that are hard to get out of. However, as long as you get yourself into some good habits as described above, you shouldn't go too far wrong. It is also worth mentioning that Git is much easier to use than it was 10 years ago. - -This section will be added to over time, and includes some useful commands/sequences to help you fix common problems. - -### Reverting a change you made to a file that you haven't yet added to the commit list - -If you've changed a file, but have not yet run the `git add file-path` command to add it to the commit list, you can revert it to the state it was when you first checked out the branch by running - -```bash -git restore file-path -``` - -### Removing a file from the commit list - -If you've already run the `git add file-path` command to add a file to the commit list, but now want to remove it from the commit list, you can use the command - -```bash -git restore --staged file-path -``` - -### Reversing a commit - -If you've committed the commit list using `git commit -m 'my commit message'`, and not yet pushed it, but now realized that you put something in there that you want to remove, you can reverse your local commit using - -```bash -git reset HEAD~1 -``` - -This will take it back to the state when the changes in that commit are not yet added to the commit list (you would need to git add them again after figuring out the problem). Note that this gets you back to the state before you started committing anything in this session. This won't help you if you need to do something more complex, like only revert the middle commit out of a set of three. We'll leave it there for this lesson. - -### Reversing a commit that has been pushed to the remote fork - -At this point, there is not really any going back, or rewinding. Instead, you need to push another commit to reverse the effects of the one you want to get rid of. You could do this manually using some of the tools we've already given you above, but there is a built-in command that makes this easier — `git revert`. This can be used to automatically create a commit that reverts changes back to the point you specify. - -1. At its simplest, you can run the following command to create a commit that will get your remote branch back to the state you were in before you started committing: - - ```bash - git revert HEAD - ``` - -2. This will result in a commit message file being opened up in your default text editor that you need to check to make sure you are happy with it. Close this, and git will finalize creating the commit. -3. Now you just need to push it: - - ```bash - git push - ``` - -If you look at your remote fork's github.com page again, you'll see the commit that you wanted to reverse, plus the commit that reverses it. - -> **Note:** Another way to handle getting rid of files that have ended up in pull requests that you don't want to be there is to use the GitHub UI. Go to your pull request's page on github.com, go to the "Files changed" tab, and find the file you want to remove from the pull request. At the top right of the file's box in the page there will be a "three dot" (`...`) menu. Press this button and choose "Delete file". In the confirmation page, enter a title for the new commit, make sure the "Commit directly…" checkbox is selected, and press the "Commit changes" button. -> -> It is usually a good idea to get the rest of the pull request looking exactly how you want it before you make changes via the GitHub UI. If you do something like this and then end up having to make more changes, you'll need to remember to pull the changes you made to your remote branch down to your local branch (e.g. with `git pull`) before you can push more commits. - -### Want to see more? - -If you think this troubleshooting guide should contain more information, please [create an issue](https://github.com/mdn/content/issues/new) to suggest what you think we should include. - -## See also - -- [MDN Learn > Git and GitHub](/en-US/docs/Learn/Tools_and_testing/GitHub) -- [Dangit, Git](https://dangitgit.com/en) — additional useful troubleshooting techniques -- [45 GitHub Issues Dos and Don'ts](https://hackernoon.com/45-github-issues-dos-and-donts-dfec9ab4b612) -- [gh CLI tool](https://cli.github.com/) — once you are used to using the vanilla git CLI commands to control your repos, you might want to consider installing GitHub's own gh CLI tool, which provides commands to speed up a number of the processes discussed above. diff --git a/files/en-us/mdn/contribute/github_beginners/new-branch.png b/files/en-us/mdn/contribute/github_beginners/new-branch.png deleted file mode 100644 index 7b1ff4abc7dd8b9..000000000000000 Binary files a/files/en-us/mdn/contribute/github_beginners/new-branch.png and /dev/null differ diff --git a/files/en-us/mdn/contribute/github_beginners/open-pull-request.png b/files/en-us/mdn/contribute/github_beginners/open-pull-request.png deleted file mode 100644 index f944edb1d5a4243..000000000000000 Binary files a/files/en-us/mdn/contribute/github_beginners/open-pull-request.png and /dev/null differ diff --git a/files/en-us/mdn/contribute/github_best_practices/index.md b/files/en-us/mdn/contribute/github_best_practices/index.md deleted file mode 100644 index 936cbe334692764..000000000000000 --- a/files/en-us/mdn/contribute/github_best_practices/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: GitHub best practices for MDN -slug: MDN/Contribute/GitHub_best_practices -tags: - - Best practices - - Community - - GitHub - - MDN ---- -{{MDNSidebar}} - -This page contains best practices for working with GitHub to contribute to MDN, mainly centered around how to work with issues. - -## 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/contribute/github_cheatsheet/index.md b/files/en-us/mdn/contribute/github_cheatsheet/index.md deleted file mode 100644 index 4ddc89b3d4fe692..000000000000000 --- a/files/en-us/mdn/contribute/github_cheatsheet/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: GitHub cheatsheet -slug: MDN/Contribute/GitHub_cheatsheet -tags: - - Best practices - - Community - - GitHub - - MDN - - Beginners - - Cheatsheet - - Commands ---- -{{MDNSidebar}} - -This article provides a quick reference to the essential commands you'll need when using [Git](https://git-scm.com/) and [GitHub](https://github.com/) to contribute to MDN. If you are new to these tools and need a helping hand, our [GitHub for complete beginners](/en-US/docs/MDN/Contribute/GitHub_beginners) tutorial teaches the basics. - -## Cloning - -```bash -git clone the-repo-url -``` - -## Setting up a remote - -```bash -git remote add remote-name repo-you-want-to-point-to -``` - -## View remotes list - -```bash -git remote -v -``` - -## Preparing to make a change to the repo - -### Switch to the main branch - -```bash -git switch main -``` - -### Update your main branch - -```bash -git fetch remote-name -git rebase remote-name/main -git push -``` - -## Get your branch locally and switch to it - -```bash -git pull -git switch new-branch -``` - -## Get latest status - -```bash -git status -``` - -## Adding, committing, and pushing changes - -```bash -git add path-to-changed-file -git commit -m 'my commit message' -git push -``` - -## Troubleshooting - -### Reverting a change you made to a file that you haven't yet added to the commit list - -```bash -git restore file-path -``` - -### Removing a file from the commit list - -```bash -git restore --staged file-path -``` - -### Reversing the last commit - -```bash -git reset HEAD~1 -``` - -### Reversing a commit that has been pushed to the remote fork - -```bash -git revert HEAD -git push -``` - -> **Note:** Another way to handle getting rid of files that have ended up in pull requests that you don't want to be there is to use the GitHub UI. Go to your pull request's page on github.com, go to the "Files changed" tab, and find the file you want to remove from the pull request. At the top right of the file's box in the page there will be a "three dot" (`...`) menu. Press this button and choose "Delete file". In the confirmation page, enter a title for the new commit, make sure the "Commit directly…" checkbox is selected, and press the "Commit changes" button. - -## Want to see more? - -If you think this cheatsheet should contain more commands, please [create an issue](https://github.com/mdn/content/issues/new) to suggest what you think we should include. diff --git a/files/en-us/mdn/contribute/help_beginners/index.md b/files/en-us/mdn/contribute/help_beginners/index.md deleted file mode 100644 index c39ab31539b69f6..000000000000000 --- a/files/en-us/mdn/contribute/help_beginners/index.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Help beginners to learn on MDN! -slug: MDN/Contribute/Help_beginners -tags: - - Beginner - - Contribute - - HELP - - Learning - - MDN ---- -{{MDNSidebar}} - -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/contribute/howto/migrate_external_content_to_mdn/index.md b/files/en-us/mdn/contribute/howto/migrate_external_content_to_mdn/index.md deleted file mode 100644 index 6bc4ee2f3af7793..000000000000000 --- a/files/en-us/mdn/contribute/howto/migrate_external_content_to_mdn/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: How to migrate external content to MDN Web Docs -slug: MDN/Contribute/Howto/Migrate_external_content_to_MDN -tags: - - Content migration - - MDN Meta ---- -{{MDNSidebar}} - -You will sometimes identify already-existing content that would make sense to migrate onto MDN Web Docs from elsewhere. This article covers what kinds of content potentially make sense to migrate, whether you should migrate content or not, and what workflow to use to undertake the migration. - -## What content would make sense to migrate? - -There are a number of content types that it would potentially make sense to migrate onto MDN Web Docs: - -- Tutorials/Guides: Practical information on using a technology. These are useful on MDN Web Docs in a variety of places depending on level and coverage (e.g. [Using Fetch](/en-US/docs/Web/API/Fetch_API/Using_Fetch), [Creating hyperlinks](/en-US/docs/Learn/HTML/Introduction_to_HTML/Creating_hyperlinks)). -- Explainers/concept articles: These generally deal with explaining high-level concepts such as why an API is structured like it is, what problems it is designed to solve, etc. These would make sense as "Concepts" articles (for example [WebVR concepts](/en-US/docs/Web/API/WebVR_API/Concepts)). -- Code examples: MDN Web Docs really values good code examples, whether it is code snippets to put inside reference articles or full examples to link to. We are happy to welcome good code examples into our GitHub repos, either as standalone examples, or part of our [interactive-examples repo](https://github.com/mdn/interactive-examples). - -Content that doesn't make sense to migrate to MDN Web Docs: - -- Lengthy case studies -- Product documentation -- Promotional content - -## Why would you migrate the content? - -If good developer content exists already, it makes sense to migrate it to MDN Web Docs for a number of reasons: - -- SEO: MDN Web Docs is a very popular site — putting your content on there is a good way to make it more findable. -- Not reinventing the wheel: MDN Web Docs documentation is prided on being complete, meaning that we'll need to write all essential references and tutorials on site rather than linking off to other places. Putting an existing tutorial on here means that we won't have to write it ;-) -- Revisions and maintenance: If you put your content on MDN Web Docs, you'll have the full support of our writer's team and community in helping to review, edit and maintain the work. - -## Should you migrate the content? - -If the content is high quality and meets the above content type criteria, then it sounds like a good thing to migrate it. However, you should consider the below points first before you make a move: - -- Duplicating content: Does the resource you want to move duplicate content that is already on MDN Web Docs? If so, it might make sense to help improve the existing resource instead of moving another resource over. If the external resource is much better than the existing resource, then move it over and make sure the old resource is redirected to the new one. -- Where to put it: If you are not sure where to move a resource, talk to us about it first so we can help you (see [Join the conversation](/en-US/docs/MDN/Contribute/Feedback#join_the_conversation)). -- Ownership: If you do not own the rights to the content, then you cannot just move it without getting permission from the owners. You should contact them and talk about it first. If the content is published under some kind of permissive license scheme (e.g. Creative Commons or GPL) then make sure the license conditions are satisfied. Feel free to ask us for advice also. -- Keeping community happy: Even if you own the content, if there is a community built around it you should consult them — get their input, make sure they understand what is going on, minimize any confusion or annoyance that can result in moving the content. -- Redirects: When you move a content resource, you will usually want to redirect the old content to the new location, so that links do not break. In a few cases where this doesn't make sense — for example if the moved content is a copy of an original template, and both make sense in the context they are found in — it often still makes sense to provide a link somewhere to the new version, so the relationship between the two is clear. -- Making sense: When the content has been moved, do the resources in the old and new locations still make sense? You might need to update descriptions or navigation menus to ensure this. - -## Workflow for migration - -What follows is a sample workflow for migrating content onto MDN Web Docs. We migrated some W3C Payment Request code to MDN, as recorded in [this GitHub issue](https://github.com/w3c/payment-request-info/issues/4). - -1. Identify the resource to be migrated. -2. Identify who owns the content, and talk to them and their associated community to make sure moving the content is not going to be a problem. -3. Identify an MDN Web Docs contact who can help you with the migration. If in doubt, [ask for help](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help). -4. Looking at [our GitHub content repo](https://github.com/mdn/content), identify the location where the content should be put, making sure that it doesn't duplicate existing content (see above). -5. Move the content over, making changes as necessary so it fits MDN style. -6. Request a review from the MDN team/community -7. Redirect the old resource to the new location, as appropriate. diff --git a/files/en-us/mdn/contribute/howto/report_a_problem/index.md b/files/en-us/mdn/contribute/howto/report_a_problem/index.md deleted file mode 100644 index 28fa6b9af001c2f..000000000000000 --- a/files/en-us/mdn/contribute/howto/report_a_problem/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: How to report a problem on MDN -slug: MDN/Contribute/Howto/Report_a_problem -tags: - - Guide - - Howto - - MDN Meta ---- -{{MDNSidebar}} - -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. diff --git a/files/en-us/mdn/contribute/localize/index.md b/files/en-us/mdn/contribute/localize/index.md deleted file mode 100644 index 25e2aa9a3adefd3..000000000000000 --- a/files/en-us/mdn/contribute/localize/index.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Localizing MDN -slug: MDN/Contribute/Localize -tags: - - Localization - - MDN Meta - - l10n ---- -{{MDNSidebar}} - -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: [Nathália Pissuti](https://github.com/nathipg), [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), [yin1999](https://github.com/yin1999) - -### 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), [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), [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), [davbrito](https://github.com/davbrito), [Graywolf9](https://github.com/Graywolf9), [Vallejoanderson](https://github.com/Vallejoanderson), [marcelozarate](https://github.com/marcelozarate), [Jalkhov](https://github.com/Jalkhov) - -> **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/contribute/open_source_etiquette/index.md b/files/en-us/mdn/contribute/open_source_etiquette/index.md deleted file mode 100644 index d852bf146f12672..000000000000000 --- a/files/en-us/mdn/contribute/open_source_etiquette/index.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Basic etiquette for open source projects -slug: MDN/Contribute/Open_source_etiquette -tags: - - Best practices - - Community - - Open source - - MDN - - Beginners ---- -{{MDNSidebar}} - -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 (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 skills. -- I want to publicly demonstrate my skills as part of my college or university course. -- I want to publicly demonstrate my 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. - -Some not-so-good reasons to start contributing are: - -- I want someone to talk to. -- I want some people to troll/boss around. -- I want to show off how amazing I am. - -Your presence on the project should be productive, and it shouldn't stop others from being so too. - -## Be polite, be kind, and 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, when they land their first 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 the 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 on MDN, 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 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 , broken up by various GitHub labels into estimated time to fix, technology categories, and more. Another good label to look for is "good first issue", which is generally given to issues that are quite simple and good for beginners to get started with. We are also soon going to start triaging our issues more extensively, by adding other labels such as priority indicators. Try picking some issues that you think you can manage with the time you have available, and ask to be assigned to them. - -You could also contribute by opening 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 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 an 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 contributors' 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/contribute/processes/content_bug_triage/index.md b/files/en-us/mdn/contribute/processes/content_bug_triage/index.md deleted file mode 100644 index 439086908bf4410..000000000000000 --- a/files/en-us/mdn/contribute/processes/content_bug_triage/index.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Triage process for MDN content bugs -slug: MDN/Contribute/Processes/Content_bug_triage -tags: - - MDN - - MDN Meta - - Meta - - Meta Docs - - Content bugs - - Process - - Triage ---- -{{MDNSidebar}} - -This document looks at the process for triaging content bugs and getting them ready for contributors to effectively work on. - -## Reporting and working on bugs - -Anyone can report a content bug by writing an issue at using the "Content bug" issue template, or by using the "Report a problem with this content on GitHub" link at the bottom of each MDN page. - -Once reported, content bugs are listed at , and are designed to be done by individuals with minimal process requirements. Anyone is welcome to work on a content bug, using the process outlined at [Fixing MDN content bugs](/en-US/docs/MDN/Contribute/Fixing_MDN_content_bugs). - -## Overall triage process - -At a high level, the process for triage looks like so: - -Triage preparation: - -- Decide on triagers — Who will do the regular triage? -- Set initial labels — As soon as a new bug comes in, give it the "needs-triage" label, to signify that it needs to be triaged (this should happen automatically), plus a "Content:" label to signify what topic area it is in, e.g. "Content:HTML". Anyone can do this as they spot bugs coming in, but the MDN core team will keep an active eye on this. -- Set aside triage time — set out a regular 30-minute slot in which to do the triage, each week. - -Triage for each issue: - -- Checklist — run through checklist to see if it is ready to triage. -- Set priority measure — according to priority rules. -- Provide further information to help other contributors start working on bugs more easily. -- Set other labels — there are other labels to set, to help people to choose issues to work on. - -Check through old bugs — look at existing bugs, and see if there are any that are stalled, or need closing, etc. - -## Triage preparation - -### Decide on triagers - -We need an assigned triager to regularly triage bugs coming in on each MDN content area. We currently have the following triagers assigned: - -- Accessibility — Eric Bailey? -- CSS — Rachel Andrew -- DevTools — Hamish Willee -- HTML — Rachel Andrew -- HTTP — Florian Scholz -- JS — Florian Scholz -- Learn — Chris Mills -- Learn:CSS — Rachel Andrew -- Learn:Express / Learn:Django — Hamish Willee -- Media — Ruth John -- Other — Ruth John -- SVG — André Jaenisch -- WebAPI — Ruth John -- WebExt — Caitlin/WebExt team - -### Set initial labels - -As soon as a new issue is filed, the MDN core team, and anyone else who wishes to help, will add the following labels to that issue: - -- `needs-triage` — signals that this issue needs a proper triage, to get it ready to work on (this should happen automatically). -- `Content:` — specifies the content topic this issue relates to, e.g. `Content:HTML` or `Content:CSS`. This needed for the triagers to be able to find the issues in their specific areas. -- `l10n-fr`, `l10n-zh`, `l10n-ja` — specifies that the issue filed concerns an active non-en-US locale. The teams for those locales will pick these issues up and triage them. - -### Set aside triage time - -Triagers don't need to be actively triaging bugs all the time. Instead, they should set out a 30-minute slot in which to triage the bugs in their area of responsibility, each week. - -This doesn't have to be done as part of a synchronous meeting, or even at the same time as everyone else, but it should be done regularly, say once per week, to make sure that the backlog of untriaged bugs doesn't get too high. - -## Triage process for each issue - -### Checklist to determine if we have enough information - -For each bug, run through the following checklist to make sure the issue contains enough information for someone to start working on the bug. - -Does the issue contain: - -- The MDN URL where the problem has been found. -- The URL of any example page or repo related to the bug, if appropriate. -- The specific heading on the MDN page where the problem can be found (if needed to find it). -- A clear description of what the problem is. - -If this information is not present, then the triager should ask the submitter of the issue to provide these details, and not continue triaging the issue until those details are provided. - -### Set priority measure - -For each bug, set a priority measure label to help people who want to work on the most important issues or areas (rather than the topics they are interested in). - -The levels of priority are: - -- `P0` — A critical issue on any MDN doc. -- `P1` — A major issue on a Tier 1 MDN doc. -- `P2` — A minor issue on a Tier 1 MDN doc. -- `P3` — A major issue on a Tier 2 MDN doc. -- `P4` — A minor issue on a Tier 2 MDN doc. - -Definitions: - -- Critical issue — Something that could damage MDN's reputation severely and/or harm users, which we need to fix as soon as possible, regardless of where it appears on the site. Examples include code examples that if used in production could create a severe security issue, undesirable content such as malware, profanity, pornography, hate speech, or other undesirable content, or links to such content. -- Major issue — Something that could severely affect a page's usefulness, for example a significant amount of out-of-date information, a complex and important code example that doesn't work, a significant amount of prose that is badly written and hard to understand, a large number of broken links, etc. -- Minor issue — something that doesn't look great but does not affect learning, or only has a minor effect on learning. Examples — Typos, bad grammar, a broken link, a small amount of out-of-date information or badly-written prose, a small code snippet that doesn't work. - -Generally speaking, critical issues should be fixed immediately, and would probably be handled by MDN staff/peers. And Tier 1 issues are more important than Tier 2 issues. Folks that are interested in tackling the highest priority MDN issues should always tackle Tier 0 issues if any are available, before moving on to Tier 1 then Tier 2 issues. - -> **Note:** For definitions of Tier 1 and Tier 2, see the [MDN documentation priority list](https://mdn-contributor-docs.mozilla.org/legacy/documentation-priorities/). - -### Provide further information - -It is really useful for other contributors to provide them with further information to help them fix issues; we'd like to recommend that triaging each bug involves a time-box of up to 5 minutes in which the triager quickly describes some steps to take to fix the bug, to help the person who eventually tries to fix it. - -For example: - -```plain -To whoever fixes this issue, it looks like the following is needed: - -* Update the first paragraph below heading X to correct the problem with Y -* Add a description of X -* Update the compatibility data at Link-X -``` - -### Set other labels - -Next, set other labels as appropriate: - -- `10 minute task`, `30 minute task`, `1 hour task`, `multiple hour task` — Some people like to search for bugs based on how much time they've got to contribute, so we like to give a rough measure to allow people to choose. We appreciate that this is hard to estimate, and that different people will fix bugs at different speeds, but this is only supposed to be a rough measure. When setting it, think about how much time you think someone with a moderate-to-good amount of knowledge in the subject area would take to fix it. -- `good first issue` — if the fix for the issue is really simple, and it would be a good practice issue for a newcomer just getting used to the system, mark it with this label. -- `help wanted` — this seems to be a very popular label for people to use to search for things to do on open source projects, so we set this as a matter of course on successfully-triaged bugs. -- `broken-link-internal`, `broken-link-external` — use these if the issue involves a link to a non-existent internal page, or a broken external link. -- Once the triage process is completed, **don't forget to remove the `needs-triage label`.** - -## Check through old issues - -At the end of your triage session, have a look through the older existing triaged issues in your topic area, and check to make sure none of the issues are being unnecessarily stalled or clogged up: - -- Check assigned issues that are still open to see if the assignee is making progress. If they have done nothing after a week of being assigned, ask them if they still have to work on the issue. If another week passes and they have still done nothing, unassign them and say that you are opening this up again for others to take. -- If a PR has been issued to fix the issue but it has not been reviewed for a week, give the reviewer a gentle ping to ask if they can get to it. -- If a PR is waiting on review comments to be addressed after a week, then ask the submitter if they can respond to their review. If another week goes by, either fix the review comments yourself if you have time, or close the PR if not. diff --git a/files/en-us/mdn/contribute/where_is_everything/index.md b/files/en-us/mdn/contribute/where_is_everything/index.md deleted file mode 100644 index cd975175c98c878..000000000000000 --- a/files/en-us/mdn/contribute/where_is_everything/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Where is everything on MDN? A guide to our repos -slug: MDN/Contribute/Where_is_everything -tags: - - Best practices - - Community - - GitHub - - MDN - - Beginners - - Repos ---- -{{MDNSidebar}} - -MDN is a complex project with lots of moving parts. Contributing to the site is easy to begin with if you have a bit of GitHub knowledge and are starting out on some simple typo fixes or code snippet improvements. However, when you start making more significant contributions such as adding entirely new pages, you'll notice that there are quite a few bits of the content that aren't stored in the page sources and instead come from somewhere else. - -This article acts as a quick guide to finding the different repos you need to edit to update the different parts of MDN content. - -## Core repos - -- **Core content**: . The most important repo for MDN 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 Platform**: . This is where the MDN platform is stored, and where you'll go if you want to make changes to MDN's high level page structure or rendering machinery. -- **Browser compat 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)). Go here to make compat data changes! -- **Interactive examples**: . This repo stores the rendering code and example code blocks that together 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)). Edit those examples here. -- **Translated content**: . This is where localized content lives. Go here if you want to help translate pages into any of our actively maintained locales. -- **CSS data**: . Originally envisaged as a hold-all repo for general purpose MDN data, the data repo now serves the purpose of holding data about CSS features such as formal syntax, inheritance, computed value, animation type, etc. This is used to generate sections on CSS reference pages such as formal definition ([example](/en-US/docs/Web/CSS/font-variant-caps#formal_definition)) and formal syntax ([example](/en-US/docs/Web/CSS/font-variant-caps#formal_syntax)). - -## Other repos - -- **Demo repos**. The MDN GitHub org contains a huge number of demo repos, for example [css-examples](https://github.com/mdn/css-examples), [dom-examples](https://github.com/mdn/dom-examples), [webaudio-examples](https://github.com/mdn/webaudio-examples). These generally contain free-standing examples that are often linked to from MDN 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)}}. If you want to edit a standalone live example, it will always be found in one of these example repos. -- **MDN-minimalist**: . The base styling information for MDN. If you want to help improve MDN's CSS styling, this is the place to visit. diff --git a/files/en-us/mdn/guidelines/index.md b/files/en-us/mdn/guidelines/index.md deleted file mode 100644 index b1c063ee37e9660..000000000000000 --- a/files/en-us/mdn/guidelines/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Guidelines -slug: MDN/Guidelines -tags: - - Guidelines - - Landing - - MDN Meta ---- -{{MDNSidebar}} - -These guides provide details on how MDN documentation should be written and formatted, as well as how our code samples and other content should be presented. By following these guides, you can ensure that the material you produce is clean and easy to use. - -{{LandingPageListSubpages}}