adding complete beginner starter guides (#2874)

* adding complte beginner starter guides

* fixing markdown linting errors

README.md

@@ -53,6 +53,25 @@ A good place to learn about general guidelines for contributing to
 For example, you can find out more about MDN's writing-style guidelines via the
 [Writing style guide](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Writing_style_guide).
 
+### Prerequisite knowledge
+
+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](https://developer.mozilla.org/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](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Open_source_etiquette).
+- Git and GitHub: If you are unfamiliar with these tools, [GitHub for complete
+  beginners](https://developer.mozilla.org/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?](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Where_is_everything)
+  will point you towards the correct places.
+
 ### Setup
 
 No matter how you wish to contribute, you'll need

files/en-us/mdn/contribute/getting_started/index.html

@@ -45,3 +45,17 @@ <h3 id="Step_4_Ask_for_help">Step 4: Ask for help</h3>
 </ul>
 
 <p>Don't worry about doing it perfectly; other MDN contributors are here to help fix errors that slip through.</p>
+
+<h2 id="useful_complete_beginners_guides">Useful complete beginner's guides</h2>
+
+<p>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&#39;d advise you to look at the provided links to help you get up to
+speed:</p>
+
+<ul>
+  <li>Web technologies: If you are new to HTML, CSS, JavaScript, etc., check out our <a href="/en-US/docs/Learn">Learn web development</a> tutorials.</li>
+  <li>Open source: If you&#39;ve never contributed to an open source project before, have a read of <a href="/en-US/docs/MDN/Contribute/Open_source_etiquette">Basic etiquette for open source projects</a>.</li>
+  <li>Git and GitHub: If you are unfamiliar with these tools, <a href="/en-US/docs/MDN/Contribute/GitHub_beginners">GitHub for complete beginners</a> will get you started.</li>
+  <li>MDN&#39;s repo structures: If you are not sure what repos to edit to make changes to the different parts of MDN&#39;s content, <a href="/en-US/docs/MDN/Contribute/Where_is_everything">Where is everything on MDN?</a> will point you towards the correct places.</li>
+</ul>

files/en-us/mdn/contribute/github_best_practices/index.html

@@ -1,5 +1,5 @@
 ---
-title: GitHub best practices
+title: GitHub best practices for MDN
 slug: MDN/Contribute/GitHub_best_practices
 tags:
   - Best practices
@@ -9,9 +9,9 @@
 ---
 <p>{{MDNSidebar}}</p>
 
-<p>This page is a set of best practices for working with GitHub, which are useful when contributing to many different task types on MDN.</p>
+<p>This page contains best practices for working with GitHub to contribute to MDN, mainly centered around how to work with issues.</p>
 
-<p>When choosing a GitHub issue to work on:</p>
+<h2 id="when_choosing_a_github_issue_to_work_on">When choosing a GitHub issue to work on</h2>
 
 <ol>
  <li>Write a comment in the issue saying that you would like to take it on, and we'll assign you to it.
@@ -32,7 +32,7 @@
  <li>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.</li>
 </ol>
 
-<p>When you've been assigned to an issue:</p>
+<h2 id="when_youve_been_assigned_to_an_issue">When you've been assigned to an issue</h2>
 
 <ol>
  <li>Scope out the remainder of the work that needs to be done.

files/en-us/mdn/contribute/github_cheatsheet/index.html

@@ -0,0 +1,77 @@
+---
+title: GitHub cheatsheet
+slug: MDN/Contribute/GitHub_cheatsheet
+tags:
+  - Best practices
+  - Community
+  - GitHub
+  - MDN
+  - Beginners
+  - Cheatsheet
+  - Commands
+---
+<p>{{MDNSidebar}}</p>
+
+<p>This article provides a quick reference to the essential commands you'll need when using <a href="https://git-scm.com/">Git</a> and <a href="https://github.com/">GitHub</a> to contribute to MDN. If you are new to these tools and need a helping hand, our <a href="/en-US/docs/MDN/Contribute/GitHub_beginners">GitHub for complete beginners</a> tutorial teaches the basics.</p>
+
+<h2 id="Cloning">Cloning</h2>
+
+<pre class="brush: bash">git clone <em>the-repo-url</em></pre>
+
+<h2 id="setting_up_a_remote">Setting up a remote</h2>
+
+<pre class="brush: bash">git remote add <em>remote-name</em> <em>repo-you-want-to-point-to</em></pre>
+
+<h2 id="view_remotes_list">View remotes list</h2>
+
+<pre class="brush: bash">git remote -v</pre>
+
+<h2 id="preparing_to_make_a_change_to_the_repo">Preparing to make a change to the repo</h2>
+
+<h3 id="switch_to_the_main_branch">Switch to the main branch</h3>
+
+<pre class="brush: bash">git switch main</pre>
+
+<h3 id="update_your_main_branch">Update your main branch</h3>
+
+<pre class="brush: bash">git fetch <em>remote-name</em>
+git rebase <em>remote-name</em>/main
+git push</pre>
+
+<h2 id="get_your_branch_locally_and_switch_to_it">Get your branch locally and switch to it</h2>
+
+<pre class="brush: bash">git pull
+git switch new-branch</pre>
+
+<h2 id="get_latest_status">Get latest status</h2>
+
+<pre class="brush: bash">git status</pre>
+
+<h2 id="adding_committing_and_pushing_changes">Adding, committing, and pushing changes</h2>
+
+<pre class="brush: bash">git add path-to-changed-file
+git commit -m 'my commit message'
+git push</pre>
+
+<h2 id="troubleshooting">Troubleshooting</h2>
+
+<h3 id="reverting_a_change_you_made_to_a_file_that_you_havent_yet_added_to_the_commit_list">Reverting a change you made to a file that you haven't yet added to the commit list</h3>
+
+<pre class="brush: bash">git restore <em>file-path</em></pre>
+
+<h3 id="removing_a_file_from_the_commit_list">Removing a file from the commit list</h3>
+
+<pre class="brush: bash">git restore --staged <em>file-path</em></pre>
+
+<h3 id="reversing_a_commit">Reversing the last commit</h3>
+
+<pre class="brush: bash">git reset HEAD~1</pre>
+
+<h3 id="reversing_a_commit_that_has_been_pushed_to_the_remote_fork">Reversing a commit that has been pushed to the remote fork</h3>
+
+<pre class="brush: bash">git revert HEAD
+git push</pre>
+
+<h2 id="want_to_see_more">Want to see more?</h2>
+
+<p>If you think this cheatsheet should contain more commands, please <a href="https://github.com/mdn/content/issues/new">create an issue</a> to suggest what you think we should include.</p>

files/en-us/mdn/contribute/open_source_etiquette/index.html

@@ -0,0 +1,165 @@
+---
+title: Basic etiquette for open source projects
+slug: MDN/Contribute/Open_source_etiquette
+tags:
+  - Best practices
+  - Community
+  - Open source
+  - MDN
+  - Beginners
+
+---
+<p>{{MDNSidebar}}</p>
+
+<p>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.</p>
+
+<p>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 and learn more about as you get started with open source contributions.</p>
+
+<h2 id="think_about_why_you_are_contributing_to_an_osp">Think about why you are contributing to an OSP</h2>
+
+<p>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.</p>
+
+<p>Even better reasons might include:<p>
+
+<ul>
+  <li>I use this tool all the time and found a bug in it/want to help make it better.</li>
+  <li>I want to help other people use the tool more successfully.</li>
+  <li>I want to help other people contribute to the project more successfully.</li>
+  <li>I want to improve my own skills.</li>
+  <li>I want to publicly demonstrate my own skills as part of my college or university course.</li>
+  <li>I want to publicly demonstrate my own skills to improve my chances of getting a job.</li>
+</ul>
+
+<p>Some of these reasons are self-serving, but that's OK too — if you are spending your time working on a project for free, then it is reasonable to expect to get something out of it, and in fact you are far more likely to stick around for longer and contribute more productively to the project. In addition, having a good set of reasons for contributing clear before you start will help make it easier to decide what tasks to start on.</p>
+
+<p>Some not so good reasons to start contributing are:</p>
+
+<ul>
+  <li>I want someone to talk to.</li>
+  <li>I want some people to troll/boss around.</li>
+  <li>I want to show off how amazing I am.</li>
+</ul>
+
+<p>Your presence on the project should still be productive, and not stop others from being productive.</p>
+
+<h2 id="be_polite_be_kind_avoid_incendiary_or_offensive_language">Be polite, be kind, avoid incendiary or offensive language</h2>
+
+<p>We could abbreviate this to "be kind". This is our number one bit of advice for anyone starting open source contributions.</p>
+
+<p>Be kind to the other contributors on the project, and it will be a happier and more productive place. This includes:</p>
+
+<ul>
+  <li>Thanking people if they help you.</li>
+  <li>Congratulating people where appropriate (for example if they land their first ever pull request, or fix a particularly difficult bug).</li>
+  <li>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.</li>
+  <li>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".</li>
+</ul>
+
+<p>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:</p>
+
+<ul>
+  <li>Knowledge of the project and the technologies used to build it</li>
+  <li>Gender, sexuality, age, languages spoken, location, political views, religion, or other personal attributes</li>
+  <li>Experience with open source projects</li>
+  <li>Confidence</li>
+  <li>Expectations</li>
+  <li>Sense of humor</li>
+</ul>
+
+<p>You should therefore keep what you write on topic as much as possible, staying away from potential controversial off-topic subjects like religion or politics, and being supportive and respectful even if you disagree with someone, or don't like a decision they've made.</p>
+
+<p>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.</p>
+
+<p>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.</p>
+
+<p>For example, MDN's repos are governed by the wide-reaching <a href="https://www.mozilla.org/en-US/about/governance/policies/participation/">Mozilla Community Participation Guidelines</a>. 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.</p>
+
+<p>If you receive anything that makes you feel uncomfortable, you should always report it using the mechanism provided on the code of conduct.</p>
+
+<h2 id="choose_impactful_contributions">Choose impactful contributions</h2>
+
+<p>Think about what you want to do on the project. For example, we have a large list of issues filed at <a href="https://github.com/mdn/content/issues">https://github.com/mdn/content/issues</a>, 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 the project 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 OK with the time you have available, and ask to be assigned to them.</p>
+
+<p>You could also contribute by opening pull requests to fix problems that you come across while reading MDN articles.</p>
+
+<p>A lot of the work on MDN revolves around writing documentation and code examples, but there are other ways to contribute too:</p>
+
+<ul>
+  <li>Help to triage issues that come in.</li>
+  <li>Help fix typos.</li>
+  <li>Help to improve grammar and make pages more understandable.</li>
+  <li>Help to mentor people that are trying to make fixes.</li>
+</ul>
+
+<p>Every fix is useful, no matter how small, and we won't turn any fix away. Saying that however, try to make sure your fixes are productive. We'd like to advise against these kinds of contributions:</p>
+
+<ul>
+  <li>Updating code styling just because "you like that style better".</li>
+  <li>Updating language style "just because you like that style better".</li>
+  <li>Changing pages from US English to British English.</li>
+  <li>Adding or removing a bunch of punctuation when there's not really anything wrong.</li>
+  <li>Changing the testing framework we are using for something else because you prefer it.</li>
+</ul>
+
+<p>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!</p>
+
+<h2 id="read_the_manual">Read the manual</h2>
+
+<p>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 <a href="https://github.com/mdn/content/blob/main/README.md">README</a> and a decent set of contributor docs on the site itself (see <a href="/en-US/docs/MDN/Contribute">Contributing to MDN</a>).</p>
+
+<p>The one ask here is — don't be afraid to ask for help, but ALWAYS try to find the answer to your question first before asking. This way you build up your knowledge of the project and become more independent, and don't put unnecessary burden on the other contributors.</p>
+
+<p>Of course, the docs won't always be perfect. If you find something that is hard to find or not explained very well, file an issue, or create a pull request to try to fix it yourself.</p>
+
+<h2 id="find_out_where_to_ask_questions">Find out where to ask questions</h2>
+
+<p>Always find out where the best place is to ask questions. Good OSPs will always make this clear in their docs (see <a href="/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help">ask for help on MDN</a>). 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).</p>
+
+<h2 id="make_progress_not_noise">Make progress, not noise</h2>
+
+<p>Think carefully about the way you handle communication in the project — make sure it is useful, and that it doesn't make other contributor's jobs harder. Submitting pull requests to fix bugs is great, but are they truly useful, and easy to review? Filing issues and joining in other conversations is fine, but are your issues and comments on topic, or are they just adding noise?</p>
+
+<p>As a rule, do:</p>
+
+<ul>
+  <li>Discuss one topic per issue — it is easy to keep issues focused and productive.</li>
+  <li>Fix one issue per PR — it my be slightly more work for you, but it is much easier to review a single clear fix.</li>
+  <li>Contribute to other threads if you have a useful point to make or can answer some else's question.</li>
+  <li>Ask questions using other mechanisms like chat rooms or forums if you are not sure whether something is useful or have a simple question.</li>
+  <li>Read the manual first to try to answer the question yourself before asking it.</li>
+</ul>
+
+<p>Don't:</p>
+
+<ul>
+  <li>Complicate issues by trying to discuss multiple topics at once, or making off-topic comments.</li>
+  <li>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).</li>
+  <li>Open lots of issues asking vague questions.</li>
+  <li>Ask questions without trying to solve the problem yourself first.</li>
+</ul>
+
+<h2 id="osps_are_a_democracy_almost">OSPs are a democracy (almost)</h2>
+
+<p>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.</p>
+
+<p>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.</p>
+
+<p>It is useful to get to know any project's moderators, so you know who best to ask for help, for example in pull request or issue threads.</p>
+
+<h2 id="be_patient_be_timely">Be patient, be timely</h2>
+
+<p>Bear in mind that many people working on OSPs are doing it in their own 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.</p>
+
+<p>It is reasonable to wait a few days and then ping someone politely to ask if they've had time to look at it, and maybe follow up again after a week has passed to ask if they are too busy right now.</p>
+
+<p>It is NOT reasonable to start demanding things, like you are owed a quick reply. You are not.</p>
+
+<p>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.</p>
+
+<h2 id="see_also">See also</h2>
+
+<ul>
+  <li><a href="https://opensource.guide/how-to-contribute/">How to Contribute to Open Source</a></li>
+  <li><a href="https://github.com/freeCodeCamp/how-to-contribute-to-open-source">More general freeCodeCamp "How to contribute to open source" list</a></li>
+  <li><a href="https://stackoverflow.blog/2020/08/03/getting-started-with-contributing-to-open-source/">Getting started with contributing to open source</a></li>
+</ul>