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.

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

Daily markdownlint #19211

Merged
merged 1 commit into from
Aug 6, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion files/en-us/learn/html/cheatsheet/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,7 @@ format&#x3C;/code>.</pre

"Block elements," on the other hand, take up the entire width of a webpage. They also take up a full line of a webpage; they do not fit together side-by-side. Instead, they stack like paragraphs in an essay or toy blocks in a tower.

> **Note:** Because this cheatsheet is limited to a few elements representing specific structures or having special semantics, the [`div`](/en-US/docs/Web/HTML/Element/div) element is intentionally not included — because the `div` element doesnt represent anything and doesnt have any special semantics.
> **Note:** Because this cheatsheet is limited to a few elements representing specific structures or having special semantics, the [`div`](/en-US/docs/Web/HTML/Element/div) element is intentionally not included — because the `div` element doesn't represent anything and doesn't have any special semantics.

<table class="standard-table">
<thead>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ To contribute, you will need a GitHub account. If you do not already have one, g
- [Learn web development](https://developer.mozilla.org/docs/Learn): If you are new to HTML, CSS, JavaScript, we have some great content to help you get started.
- [Deep dive into collaborating with pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests)

Some writing-specific contribution opportunities will require a reasonable understanding of the English language. That said, do not let perfect be the enemy of good enough. Even if your grammar isnt good, dont worry about it! We have a team of people who aim to ensure that MDNs contents are as good as possible. In addition, someone will be along to ensure your work is tidy and well-written.
Some writing-specific contribution opportunities will require a reasonable understanding of the English language. That said, do not let perfect be the enemy of "good enough." Even if your grammar isn't good, don't worry about it! We have a team of people who aim to ensure that MDN's contents are as good as possible. In addition, someone will be along to ensure your work is tidy and well-written.

Once youve decided what kind of task you want to work on, it is time to head over to the [contributors task board](https://github.com/orgs/mdn/projects/25/views/1), pick an issue, and let us know by commenting on the issue and tagging the `@mdn/mdn-community-engagement` team. Someone from the team will respond and assign the issue to you.
Once you've decided what kind of task you want to work on, it is time to head over to the [contributors task board](https://github.com/orgs/mdn/projects/25/views/1), pick an issue, and let us know by commenting on the issue and tagging the `@mdn/mdn-community-engagement` team. Someone from the team will respond and assign the issue to you.

This ensures that two people do not work on the same issue, and you will know who to contact should you get stuck.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ A Tier 3 project needs 1 admin.

[//]: # "TODO: UPDATE WITH REPO TRIAGE"

The MDN Web Docs GitHub org contains a huge number of example repos. These generally contain free-standing code examples that are often linked to from our pages, but occasionally youll 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)}}`.
The MDN Web Docs GitHub org contains a huge number of example repos. These generally contain free-standing code examples that are often linked to from our pages, but occasionally you'll find one of these examples embedded into a page using a macro call like this — `{{EmbedGHLiveSample("css-examples/learn/tasks/grid/grid1.html", '100%', 700)}}`.

Always remember, if you are updating the code on any given page, you'll need to update the corresponding example repo as well.

Expand Down
4 changes: 2 additions & 2 deletions files/en-us/mdn/community/issues/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,15 +54,15 @@ Priority:

## Make progress, not noise

Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesnt make other contributors jobs harder. Submitting pull requests to fix issues is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise?
Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn't make other contributors jobs harder. Submitting pull requests to fix issues is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise?

As a rule, do:

- Use [GitHub discussion](https://github.com/mdn/mdn-community/discussions) before filing an issue. This helps to keep issues focused and productive.
- Ask questions using other mechanisms like [chat rooms](https://chat.mozilla.org/#/room/#mdn:mozilla.org) or [forums](<(https://discourse.mozilla.org/c/mdn/236)>) if you are not sure whether something is useful or have a simple question.
- Read the [contributor documentation]() and [how to write documentation]() first to try to solve the issue yourself.

Dont:
Don't:

- Complicate issues by trying to discuss multiple topics at once, or making off-topic comments.
- Open lots of issues asking vague questions.
Expand Down
14 changes: 7 additions & 7 deletions files/en-us/mdn/community/mdn_content/pull_requests/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This section describes how contributors make changes on MDN Web Docs and how the
Content changes we get on MDN Web Docs are related to a variety of work streams, some of which include:

- **Day-to-day content improvement work**: This includes documentation of new APIs, new CSS properties, and other significant content additions. This is usually done by MDN Web Docs staff working for Mozilla, Google, Open Web Docs, Samsung, etc., but also sometimes by community volunteers.
- **"Drive-by fixes**: This includes small updates done to the site to fix typos, grammatical issues, and technical inaccuracies. These issues are usually found by users of MDN Web Docs.
- **"Drive-by" fixes**: This includes small updates done to the site to fix typos, grammatical issues, and technical inaccuracies. These issues are usually found by users of MDN Web Docs.
- **Content bug fixes**: These are usually done by volunteers to close issues on mdn/content repo.

### How content changes are reviewed
Expand All @@ -35,10 +35,10 @@ Regardless of how content changes are done, they will be submitted as pull reque
These guidelines apply to anyone opening a PR to make a change on MDN Web Docs.

- **Open issue or discussion before opening PR**: If your PR would contain any kind of significant complexity (for example, it contains technical changes and isn't just a typo fix, grammatical improvement, or a formatting/structural change), please open an [issue](https://github.com/mdn/content/issues/new/choose) or [discussion](https://github.com/mdn/mdn-community) to describe why you're making the change, how the change would improve the content, and anything else we need to know about the change. Specifically for content suggestions or feature proposals, we have a [well documented](../../issues/content-suggestions-feature-proposals/) process to follow.
- **Keep the PR short (1 issue per PR)**: Each PR should contain a single logical change or a related set of changes that make sense to submit together. If a PR becomes too large or contains too many unrelated changes, it becomes too difficult to review, and may begin to look suspicious (it is easier to hide malicious changes in a large PR. In such cases, the reviewer has the right to close your PR, and ask that you submit a separate PR for each logical set of changes that belong together. It is also good practice to reference the relevant issue in your PR description using [GitHubs special syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). This helps maintenance as GitHub will automatically close linked issues once the PR is merged.
- **Keep the PR short (1 issue per PR)**: Each PR should contain a single logical change or a related set of changes that make sense to submit together. If a PR becomes too large or contains too many unrelated changes, it becomes too difficult to review, and may begin to look suspicious (it is easier to hide malicious changes in a large PR. In such cases, the reviewer has the right to close your PR, and ask that you submit a separate PR for each logical set of changes that belong together. It is also good practice to reference the relevant issue in your PR description using [GitHub's special syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). This helps maintenance as GitHub will automatically close linked issues once the PR is merged.
- **PR to update grammar**: PRs should not contain large amounts of grammar updates. Seemingly insignificant changes can change the meaning of technical content, so these need a careful review. Keep in mind that MDN Web Docs contains technical documentation; you should not report basic improvements in the grammar but only cases where the grammar is clearly incorrect.
- **PR to update a demo repository**: For PRs that update API usage, there needs to be an accompanying PR on the mdn/content repository to update the corresponding relevant documentation. Such a PR can be rejected if there is no corresponding content PR.
- **Only enable auto-merge for approved PRs**: It is not a recommended practice to select the Enable auto-merge (squash) checkbox on your PRs that are waiting to be reviewed or approved.
- **Only enable auto-merge for approved PRs**: It is not a recommended practice to select the "Enable auto-merge (squash)" checkbox on your PRs that are waiting to be reviewed or approved.

### Guidelines for after submitting a pull request

Expand All @@ -50,13 +50,13 @@ These guidelines apply to anyone who is tasked with reviewing MDN content PRs.

#### If you are the assigned reviewer

- **Add a starting comment**: Add a comment as soon as possible that you are aware of the PR and will start the review soon. This is an important step to avoid someone else reviewing the PR at the same time as you and so that others know its on your radar for review.
- **Ask for information from the PR author**: You can request more information to help with your review if the PR author has not explained why they are making this change. Ideally, they should reference an issue that theyre trying to fix in this PR.
- **Ask for help**: If youre open to receiving or want technical help with the review, add the `review-help-needed` label.
- **Add a starting comment**: Add a comment as soon as possible that you are aware of the PR and will start the review soon. This is an important step to avoid someone else reviewing the PR at the same time as you and so that others know it's on your radar for review.
- **Ask for information from the PR author**: You can request more information to help with your review if the PR author has not explained why they are making this change. Ideally, they should reference an issue that they're trying to fix in this PR.
- **Ask for help**: If you're open to receiving or want technical help with the review, add the `review-help-needed` label.

If you don't understand a content change that you've been selected to review or feel that it is too large and complex for you to deal with, don't panic! Feel free to reach out to someone else to ask for help, like a colleague or someone else in your group of topic review owners (if you know who they are). If you are not sure who to approach for help, then ping our `@mdn/core-yari-content` group to ask for help.

Related to the above point, it is rare that you'll be required to review a large, complex content change with no warning, like a complete page rewrite, or the addition of several new reference pages or tutorials. Usually such changes are done as part of specific work streams where the content has been approved for addition and reviewer(s) have been assigned already. In such cases, the PR should be linked to an issue that explains all these details. If you are not sure, ask the PR author if they need a review of the content, and where the rationale behind the change is explained. Ping our team on [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) to ask for help if you are still not sure or if you think the content is suspicious.

- **Close PR with unrelated changes**: You have the right to close a PR if it is too complex and/or contains multiple unrelated changes and ask the PR author to submit their changes in smaller atomic chunks.
- **Ask for load balancing help**: If your plate is full at the moment and you dont think you will be able to complete the review in a timely manner, copy the `@mdn/core-yari-content` team and ask if someone else can take up the review.
- **Ask for load balancing help**: If your plate is full at the moment and you don't think you will be able to complete the review in a timely manner, copy the `@mdn/core-yari-content` team and ask if someone else can take up the review.
Loading