Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update CONTRIBUTING.md #33523

Merged
merged 6 commits into from
May 10, 2024
Merged

Update CONTRIBUTING.md #33523

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
515ada8
Update CONTRIBUTING.md
estelle May 9, 2024
fe9350b
Link to JavaScript Landing page
hamishwillee May 9, 2024
c30d47e
Add "get in touch" link
hamishwillee May 9, 2024
d2cc0ed
Github style warnings
hamishwillee May 9, 2024
07adb63
Update CONTRIBUTING.md
hamishwillee May 9, 2024
79736ba
Update CONTRIBUTING.md
estelle May 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 13 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,18 +73,19 @@ If you've found a typo on the [JavaScript landing page][], for example, you can

1. Sign in to [GitHub](https://github.com/)
2. Navigate to [https://github.com/mdn/content](https://github.com/mdn/content)
3. Find the source file `files/en-us/web/javascript/index.md`
3. Find the source file, in this case `files/en-us/web/javascript/index.md`
4. Click the edit (pencil) button

From there, the GitHub UI will walk you through the rest by creating a [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and a branch to commit your changes to.
After you have made changes to your branch, the goal is to open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) for your changes to be incorporated.
After you have made changes to your branch, open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) with your changes to be incorporated.

A pull request represents the work you want to be reviewed, approved, and merged into the `main` branch of the MDN repository.
See the [Creating a pull request](#creating-a-pull-request) for more details on creating and handling pull requests successfully.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

on the next line, the href if empty

Copy link
Collaborator

@hamishwillee hamishwillee May 9, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@estelle I fixed and then un-fixed this. This is a reference link - so the definitions are done at the bottom of the page.

@dipikabh / @bsmth While this reference works, it is deprecated by tools such as prettier, because as an editor it is hard to tell if the link is omitted or satisfied by a later reference. Generally they look great, but they make the doc hard to read.

Prettier formats for this case to [get in touch with us][get in touch with us], and I tend to use shorter references, so I'd have something like [get in touch with us][get_in_touch].

I'm not advocating this - I think reference links should only be used if you have like 3 instances of a link in a page. Otherwise use normal links. And if you have to use a reference link, use the prettier format

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PS note some links are broken - specifically those on line 13 as the use this format: - [Writing guidelines][]. They'd work if you instead had - [Writing guidelines]. Not fixing, as I want some discussion of ^^^

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reason for using the reference style links here is for Markdownlint to catch links in this format in the rest of content:

see [this page](https://developer.mozilla.org/en-US/docs/Web/JavaScript)

And correct it to:

see [this page](/en-US/docs/Web/JavaScript)

This is fine everywhere else, but breaks in the .md files intended to be read on GitHub. As a workaround, we use this format:

See the [JavaScript landing page][] for more info...

[javascript landing page]: https://developer.mozilla.org/en-US/docs/Web/JavaScript

This was introduced here:

https://github.com/mdn/content/pull/21432/files

links are broken - specifically those on line 13 as the use this format [Writing guidelines][]

It looks weird, but it works okay: https://github.com/mdn/content/blob/main/CONTRIBUTING.md#getting-started

Here's the spec for this "shortcut reference link" syntax: https://github.github.com/gfm/#shortcut-reference-link (ex 575)


If you're not certain of the changes that you want to make, [get in touch with us][]!
If you're not certain of the changes that you want to make, [get in touch with us]!

> **Note:** You can click the **View the source on GitHub** link at the bottom of an MDN page to jump directly to the page source on GitHub.
> [!NOTE]
> You can click the **View the source on GitHub** link at the bottom of an MDN page to jump directly to the page source on GitHub.

### Forking and cloning the repository

Expand Down Expand Up @@ -191,7 +192,8 @@ To edit files and track your changes, you should use feature branches.
Feature branches are created from the `main` branch and should be named after the feature you're working on.
This will make it easier to submit a pull request for your changes.

> **Note:** Open a discussion if your changes will contain large, complex or structural changes. Ask for feedback before embarking on large tasks.
> [!NOTE]
> Open a discussion if your changes will contain large, complex or structural changes. Ask for feedback before embarking on large tasks.

1. When the server is running, make the changes you would like to make to one or more `index.md` files.

Expand Down Expand Up @@ -223,7 +225,9 @@ To ensure that all MDN documents follow the same formatting, we use both [Pretti

If you have a [local checkout](#forking-and-cloning-the-repository) of the repository and have [installed the dependencies](#preparing-the-project), or you are using [github.dev](https://github.dev), a pre-commit hook will be installed which automatically runs while making a commit. To save some headache and improve your work flow while authoring, you may wish to [configure your editor to automatically run Prettier](https://prettier.io/docs/en/editors.html). Alternatively, you may run `yarn fix:md` in the command line to manually format all Markdown files.

> **Note:** Automatically formatting changes does not work for pull requests opened using the GitHub Web UI as described in the ["Simple changes" section](#simple-changes). This may result in failed status checks on pull requests. If you're not sure about how to fix this, [get in touch with us][]! for help.
> [!NOTE]
> Automatically formatting changes does not work for pull requests opened using the GitHub Web UI as described in the ["Simple changes" section](#simple-changes).
> This may result in failed status checks on pull requests. If you're not sure about how to fix this, [get in touch with us][]! for help.

### Adding a new document

Expand All @@ -245,7 +249,7 @@ This command moves the file and fixes up redirects automatically. You can use th
yarn content move <from-slug> <to-slug> [locale]
```

> **Warning**
> [!WARNING]
> Don't edit the `_redirects.txt` file manually.
> See the [Redirecting a document](#redirecting-a-document) section for more information.

Expand Down Expand Up @@ -293,7 +297,7 @@ Let's say you want to move the entire `/en-US/Learn/Accessibility` tree to `/en-

Similar to moving files, you can delete documents or a tree of documents easily by using the `yarn content delete` command.

> **Warning:**
> [!WARNING]
> Don't delete files or directories from the repository manually; the `yarn content delete` command handles the necessary changes such as updating the `_wikihistory.json` file.

You can use this command as shown below:
Expand Down Expand Up @@ -330,7 +334,7 @@ Say you want to delete the entire `/en-US/Learn/Accessibility` tree and redirect
yarn content delete Learn/Accessibility --recursive --redirect Web/Accessibility
```

> **Warning:**
> [!WARNING]
> You should always add a redirect when deleting documents. If there is no obvious alternative, redirect to the nearest "parent" of the deleted topic.
> If you forget to redirect when deleting a file, you can do it afterwards. See the [Redirecting a document](#redirecting-a-document) section.

Expand Down