forked from mdn/content
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Migrate some README sections to contributor site (mdn#12534)
* meta docs: move "can I copy content…" to legacy * meta docs: move deployment time question to legacy section * meta docs: remove placeholder on legacy section index page * meta docs: link from README to meta docs * meta docs: move external content to legacy section * meta docs: move archiving to legacy section * meta docs: move adding code examples to legacy section * meta docs: use title/linkTitle instead of title/description * meta docs: move compat tables to legacy docs * Fix README line length * Undo prettier formatting to the whole file * Fix line length for real this time
- Loading branch information
Showing
8 changed files
with
168 additions
and
151 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| --- | ||
| title: "Archiving and unarchiving pages" | ||
| linkTitle: "Archiving" | ||
| weight: 4 | ||
| --- | ||
|
|
||
| Pages with the banner "This is an archived page. It's not actively maintained." | ||
| at the top are archived pages — they are archived because either they are | ||
| obsolete or out-of-date, or they are not in scope for MDN contributors to | ||
| actively work on. | ||
|
|
||
| If you find a page that is marked archived and you think it shouldn't be, | ||
| you can follow the below steps to unarchive it: | ||
|
|
||
| - Submit an issue to check why the page is archived and if it should be | ||
| unarchived. | ||
| - Find the source code location of the archived page. Archived pages live in | ||
| the [Archived content](https://github.com/mdn/archived-content/) repo, | ||
| the structure of which is the same as this repo (except that there are | ||
| also locale directories present other than `en-US`). As an example: | ||
| - Take the archived [Mobile developer challenge](https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Mobile_developer_challenge) | ||
| page, which is at the URL `https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Mobile_developer_challenge`. | ||
| - This page's source code is at [https://github.com/mdn/archived-content/blob/main/files/en-us/mozilla/mobile/mobile_developer_challenge/index.html](https://github.com/mdn/archived-content/blob/main/files/en-us/mozilla/mobile/mobile_developer_challenge/index.html). | ||
| - To unarchive the page, you need to open a pull request to move the page's | ||
| directory into the appropriate place inside this repo, and update the | ||
| page's meta data (like `slug`) if needed. | ||
|
|
||
| > **Note:** To archive a non-archived page, you need to follow the | ||
| > above procedure, but move the page in question the opposite way between repos. | ||
| > When removing the page from MDN, remember to use the [delete command](#deleting-a-document). | ||
| **Note:** You can have an archived page with non-archived pages below it in the | ||
| hierarchy, and vice-versa. To achieve this you need to have the same directory | ||
| structure in both the `content` and `archive-content` repos. Whether a page | ||
| is non-archived or archived depends on which repo its `index.html` file is | ||
| in. As an example, compare the [archived-content mozilla directory](https://github.com/mdn/archived-content/tree/main/files/en-us/mozilla) | ||
| with the [content mozilla directory](https://github.com/mdn/content/tree/main/files/en-us/mozilla). | ||
| Both locations represent the same directory structure, but the | ||
| `index.html` file appears in the latter, therefore the page is not archived. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| --- | ||
| title: "Adding code examples" | ||
| linkTitle: "Code examples" | ||
| weight: 4 | ||
| --- | ||
|
|
||
| There are a lot of code examples on MDN, and you'll probably want to add | ||
| some as you contribute content to the project. There are four types of | ||
| code example used on MDN: | ||
|
|
||
| - [Static examples](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Static_examples) | ||
| — plain code blocks, possibly with a screenshot to statically show the | ||
| result of such code if it were to be run. | ||
| - [Traditional MDN "live samples"](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Traditional_live_samples) | ||
| — A macro that takes plain code blocks, dynamically puts | ||
| them into a document inside an `<iframe>` element, and embeds it into the | ||
| page to show the code running live. | ||
| - [GitHub "live samples"](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#GitHub_live_samples) | ||
| — A macro that takes a document in a GitHub repo inside the [mdn organization](https://github.com/mdn), | ||
| puts it inside an `<iframe>` element, and embeds | ||
| it into the page to show the code running live. | ||
| - [Interactive examples](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples#Interactive_examples) | ||
| — Our system for creating live interactive examples that show the | ||
| code running live but also allow you to change code on the fly to see what | ||
| the effect is. | ||
|
|
||
| For a complete description of this topic, see | ||
| [the MDN code examples page](https://developer.mozilla.org/en-US/docs/MDN/Structures/Code_examples). | ||
|
|
||
| Also make sure that your code examples follow the | ||
| [MDN code example guidelines](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Code_guidelines). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| --- | ||
| title: "Updating a browser compatibility table" | ||
| linkTitle: "Compatibility tables" | ||
| weight: 4 | ||
| --- | ||
|
|
||
| The browser compatibility table shown near the bottom of many of the | ||
| MDN document pages, for example on | ||
| [the JavaScript Array page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#Browser_compatibility), | ||
| is generated from the `npm` package created from the <https://github.com/mdn/browser-compat-data> | ||
| repository. If you'd like to make or suggest a change to the content of | ||
| the browser compatibility table on any given MDN document page, you can either | ||
| use the `Report problems with this data on GitHub` link in the upper-right | ||
| corner of the table on the page itself to create an issue, or go to | ||
| <https://github.com/mdn/browser-compat-data> and | ||
| [read more to learn how to contribute](https://github.com/mdn/browser-compat-data/blob/master/docs/contributing.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| --- | ||
| title: "When will my change show up on the production MDN site?" | ||
| linkTitle: "Deployment timeline" | ||
| weight: 4 | ||
| --- | ||
|
|
||
| After your pull request is merged, it may take up to 48 hours before the | ||
| change goes live on the production <https://developer.mozilla.org/> site, | ||
| but it will usually be quicker. | ||
|
|
||
| - The complete build runs every 24h at around 7PM US/Eastern time, and is | ||
| then deployed. | ||
| - Once deployment has occurred, it can take up to 24 hours for the | ||
| associated CDN caches to replace their previously-cached content with | ||
| the updates. | ||
|
|
||
| You can use <https://whatsdeployed.io/s/DLi/mdn/content> to see if your change | ||
| has been deployed to the production site. | ||
| And use <https://whatsdeployed.io/s/16d/mdn/translated-content> for changes | ||
| to the <https://github.com/mdn/translated-content> repo. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| --- | ||
| title: "Making a change that depends on external content" | ||
| linkTitle: "External content" | ||
| weight: 4 | ||
| --- | ||
|
|
||
| Some MDN content is created from external data files or repositories using KS macros. | ||
| Generally you should create a PR to first update the external content before | ||
| updating the associated MDN pages. | ||
|
|
||
| Relevant external content includes (non-exhaustively): | ||
|
|
||
| - [GroupData.json](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json): | ||
| Data definition of | ||
| [Sidebars](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Sidebars) | ||
| used by `{{APIRef}}` macro. | ||
| - [https://github.com/mdn/interactive-examples](https://github.com/mdn/interactive-examples): | ||
| Source code repo for interactive examples inserted using the | ||
| `{{EmbedInteractiveExample}}` macro. | ||
| - [https://github.com/mdn/learning-area](https://github.com/mdn/learning-area): | ||
| Source code repo for examples referenced in the | ||
| [Learning Area](https://developer.mozilla.org/en-US/docs/Learn) | ||
| - [JSON structured data](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/JSON_Structured_Data) | ||
| provides more information about JSON data used to define inheritance diagrams | ||
| (`{{InheritanceDiagram}}` macro), specification tables, etc. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| --- | ||
| title: "Can I copy content from other sources to put on MDN?" | ||
| linkTitle: "Reuse policy" | ||
| weight: 4 | ||
| --- | ||
|
|
||
| In general, we do not approve of copying content from other sources and putting | ||
| it on MDN. MDN should be made up of original content wherever possible. If we | ||
| receive a pull request and discover that it contains plagiarized content, | ||
| we will close it and request that the submitter resubmit the change with | ||
| the content rewritten into their own words. | ||
|
|
||
| If someone wants to donate an article to MDN that they previously published on | ||
| their blog or it makes sense to copy a complex reference sheet to MDN there may | ||
| be justification for republishing it. In these cases you should discuss your | ||
| plan with the MDN team first: | ||
|
|
||
| 1. Include a comment on the relevant repo issue that explains your intention — say | ||
| what you would like to copy (include the URL) and explain why you think this | ||
| is appropriate. | ||
| 1. If the content is published under a closed license: | ||
| - If you hold the rights to the content, state this, and say that you are | ||
| happy to republish it on MDN. | ||
| - If you do not hold the rights to the content, include the author/publisher | ||
| on the issue if possible, or include details of how they could be contacted | ||
| so we can ask them for permission to republish the content. | ||
| 1. If the content is published under an open license, say what it is, and link | ||
| to the license so we can check whether it is compatible with [MDN's license](https://developer.mozilla.org/en-US/docs/MDN/About#using_mdn_web_docs_content). | ||
| 1. @-mention chrisdavidmills on the issue, so he can review the request. | ||
|
|
||
| Be warned that unless there is a good reason to republish the content, we will | ||
| probably say "no". The MDN writing team's decision is final. |