diff --git a/README.md b/README.md index 93a03780defe307..592f7a87b07cb4e 100644 --- a/README.md +++ b/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 diff --git a/files/en-us/mdn/contribute/getting_started/index.html b/files/en-us/mdn/contribute/getting_started/index.html index cf09587c13bdc13..8b4a17ff4563b06 100644 --- a/files/en-us/mdn/contribute/getting_started/index.html +++ b/files/en-us/mdn/contribute/getting_started/index.html @@ -45,3 +45,17 @@

Step 4: Ask for 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:

+ + 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 new file mode 100644 index 000000000000000..cfd7bc61de6b340 Binary files /dev/null and b/files/en-us/mdn/contribute/github_beginners/branch-button-new-branch.png 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 new file mode 100644 index 000000000000000..a19007b3d997eb2 Binary files /dev/null and b/files/en-us/mdn/contribute/github_beginners/branch-button.png 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 new file mode 100644 index 000000000000000..a2893e28693f8db Binary files /dev/null and b/files/en-us/mdn/contribute/github_beginners/branch-menu.png 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 new file mode 100644 index 000000000000000..233c741bec18647 Binary files /dev/null and b/files/en-us/mdn/contribute/github_beginners/code-popup.png 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 new file mode 100644 index 000000000000000..f4cb639948511ed Binary files /dev/null and b/files/en-us/mdn/contribute/github_beginners/compare-and-pull-request.png 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 new file mode 100644 index 000000000000000..91ab8dc24e78c31 Binary files /dev/null and b/files/en-us/mdn/contribute/github_beginners/fork-button.png differ diff --git a/files/en-us/mdn/contribute/github_beginners/index.html b/files/en-us/mdn/contribute/github_beginners/index.html new file mode 100644 index 000000000000000..981c6f7bebe9b02 --- /dev/null +++ b/files/en-us/mdn/contribute/github_beginners/index.html @@ -0,0 +1,464 @@ +--- +title: GitHub for complete beginners +slug: MDN/Contribute/GitHub_beginners +tags: + - Best practices + - Community + - GitHub + - MDN + - Beginners +--- +

{{MDNSidebar}}

+ +

Git and GitHub 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 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.

+ + + +

Assumptions made by this article

+ +

This article assumes that:

+ + + +

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, download the latest version for your computer, and install it. If you are a Windows user, you should also install the Git for Windows package, which includes Gitbash.
    2. +
  2. While you are at it, install the other required dependencies for working locally with MDN — Node.js and yarn. +
      +
    1. Install Node.js by following the above link and downloading and installing the latest version for your computer.
      2. +
    2. Once you've installed Node.js, install yarn by running npm install --global yarn.
      3. +
    +
    3. +
  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. +
  4. Sign up for a GitHub account if you don't already have one. You'll need this to contribute to MDN's repos.
    5. +
+ +

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 have created a useful guide to setting this up — see the starting point at 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), 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:

+ + + +

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.

+ +

Let's fork https://github.com/mdn/content 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

    +
    2. +
  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 https://github.com/mdn/content is available at https://github.com/chrisdavidmills/content.

    +
    3. +
+ +

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/<your-user-name>/content).

    +
    2. +
  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

    +
    3. +
  3. +

    If you set up SSH authentication as instructed above, click the "SSH" tab and copy the git@github.com:<your-user-name>/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/<your-user-name>/content.git.

    +
    4. +
  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.

    + + 
    cd git
    +
    5. +
  5. +

    Clone your fork by entering a command with the following form:

    + + 
    git clone the-url-you-copied
    + +

    So for example my cloning command looked like this:

    + + 
    git clone git@github.com:chrisdavidmills/content.git
    +
    6. +
+ +

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. https://github.com/mdn/content 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:

+ +
git remote add remote-name repo-you-want-to-point-to
+ + + +

So, to add your remote:

+ +
    +
  1. +

    Go to the github.com page for the main version of the repo (https://github.com/mdn/content in this example) and retrieve the SSH or HTTPS URL as appropriate, from the "Code" popup.

    +
    2. +
  2. +

    In your command line, cd into your content directory:

    + + 
    cd content
    +
    3. +
  3. +

    Now run a command along the following lines, replacing remote-name and repo-you-want-to-point-to as appropriate:

    + + 
    git remote add remote-name repo-you-want-to-point-to
    + +

    So for example, I used the SSH URL and called my remote "mozilla":

    + + 
    git remote add mozilla git@github.com:mdn/content.git
    +
    4. +
+ +

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:

+ +
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: + +

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 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:

    + + 
    git fetch remote-name
    + +

    So for example:

    + + 
    git fetch mozilla
    +
    2. +
  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:

    + + 
    git rebase remote-name/main-branch-name
    + +

    So for example:

    + + 

    git rebase mozilla/main
    +
    3. +
  3. +

    Finally, push those changes up to the remote version of your fork using:

    + + 
    git push
    +
    4. +
+ +

You'll know if your updates worked properly by looking at the github.com page for your fork (i.e. mine is https://github.com/chrisdavidmills/content). 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.

+ +

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 https://github.com/chrisdavidmills/content) and find the branch button at the top left hand corner of the file list, which should say "main" on it:

    + +

    Button labeled main

    +
    2. +
  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

    +
    3. +
  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

    +
    4. +
  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

    +
    5. +
+ +

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:

+ + + +

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. +
  2. You should get a message along the lines of * [new branch] test-branch -> origin/test-branch
    3. +
  3. To switch to your branch (meaning change over from "main", to work in that branch instead) run the command git switch test-branch
    4. +
+ +

If you were successful, git should tell you something like this:

+ +
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:

+ +
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, or read Contributing to MDN 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. +
  2. +

    Now go back to your command line and enter the git status command again. This time git should tell you something like this:

    + + 
    Your branch is up to date with 'origin/test-branch'.
+
+    Changes not staged for commit:
+      (use "git add <file>..." to update what will be committed)
+      (use "git restore <file>..." to discard changes in working directory)
+        modified:   README.md
+
+    no changes added to commit (use "git add" and/or "git commit -a")
    +
    3. +
  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:

    + + 
    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. +
  4. +

    If you run git status again, you'll now see this:

    + + 
    On branch test-branch
+    Your branch is up to date with 'origin/test-branch'.
+
+    Changes to be committed:
+      (use "git restore --staged <file>..." to unstage)
+        modified:   README.md
    +
    5. +
  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"): + + 

    git commit -m 'my first commit'
    + +

    Git will tell you this:

    + + 
    [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. +
  6. +

    Run git status again, and you'll get this information:

    + + 
    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
    +
    7. +
+ +

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 no errors, you should get a readout like this:

+ +
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

    + +

    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

    + +
    +

    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. +
  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. +
  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, 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. +
  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.

    +
    5. +
+ +

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

+ +
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

+ +
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

+ +
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:

    + + 
    git revert HEAD
    +
    2. +
  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. +
  3. +

    Now you just need to push it:

    + + 
    git push
    +
    4. +
+ +

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.

+ +

Want to see more?

+ +

If you think this troubleshooting guide should contain more information, please create an issue to suggest what you think we should include.

+ +

See also

+ + diff --git a/files/en-us/mdn/contribute/github_beginners/new-branch.png b/files/en-us/mdn/contribute/github_beginners/new-branch.png new file mode 100644 index 000000000000000..7b1ff4abc7dd8b9 Binary files /dev/null and b/files/en-us/mdn/contribute/github_beginners/new-branch.png 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 new file mode 100644 index 000000000000000..f944edb1d5a4243 Binary files /dev/null and b/files/en-us/mdn/contribute/github_beginners/open-pull-request.png differ diff --git a/files/en-us/mdn/contribute/github_best_practices/index.html b/files/en-us/mdn/contribute/github_best_practices/index.html index 0a66e3df44fa9b7..dc122512b5b6dff 100644 --- a/files/en-us/mdn/contribute/github_best_practices/index.html +++ b/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 @@ ---

{{MDNSidebar}}

-

This page is a set of best practices for working with GitHub, which are useful when contributing to many different task types on MDN.

+

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:

+

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. @@ -32,7 +32,7 @@
  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:

+

When you've been assigned to an issue

  1. Scope out the remainder of the work that needs to be done. diff --git a/files/en-us/mdn/contribute/github_cheatsheet/index.html b/files/en-us/mdn/contribute/github_cheatsheet/index.html new file mode 100644 index 000000000000000..caecf15d35c6f76 --- /dev/null +++ b/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 +--- +

    {{MDNSidebar}}

    + +

    This article provides a quick reference to the essential commands you'll need when using Git and GitHub to contribute to MDN. If you are new to these tools and need a helping hand, our GitHub for complete beginners tutorial teaches the basics.

    + +

    Cloning

    + +
    git clone the-repo-url
    + +

    Setting up a remote

    + +
    git remote add remote-name repo-you-want-to-point-to
    + +

    View remotes list

    + +
    git remote -v
    + +

    Preparing to make a change to the repo

    + +

    Switch to the main branch

    + +
    git switch main
    + +

    Update your main branch

    + +
    git fetch remote-name
+git rebase remote-name/main
+git push
    + +

    Get your branch locally and switch to it

    + +
    git pull
+git switch new-branch
    + +

    Get latest status

    + +
    git status
    + +

    Adding, committing, and pushing changes

    + +
    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

    + +
    git restore file-path
    + +

    Removing a file from the commit list

    + +
    git restore --staged file-path
    + +

    Reversing the last commit

    + +
    git reset HEAD~1
    + +

    Reversing a commit that has been pushed to the remote fork

    + +
    git revert HEAD
+git push
    + +

    Want to see more?

    + +

    If you think this cheatsheet should contain more commands, please create an issue to suggest what you think we should include.

    diff --git a/files/en-us/mdn/contribute/open_source_etiquette/index.html b/files/en-us/mdn/contribute/open_source_etiquette/index.html new file mode 100644 index 000000000000000..cb36d39c72d073a --- /dev/null +++ b/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 + +--- +

    {{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 and learn more 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:

    + +

    + +

    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.

    + +

    Some not so good reasons to start contributing are:

    + + + +

    Your presence on the project should still be productive, and not stop others from being productive.

    + +

    Be polite, be kind, 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:

    + + + +

    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:

    + + + +

    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.

    + +

    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. 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 impactful contributions

    + +

    Think about what you want to do on the project. For example, we have a large list of issues filed at https://github.com/mdn/content/issues, 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.

    + +

    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:

    + + + +

    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:

    + + + +

    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 and a decent set of contributor docs on the site itself (see Contributing to MDN).

    + +

    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.

    + +

    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.

    + +

    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). 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 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?

    + +

    As a rule, do:

    + + + +

    Don't:

    + + + +

    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 request or issue threads.

    + +

    Be patient, be timely

    + +

    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.

    + +

    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.

    + +

    It is NOT reasonable to start demanding things, like you are owed a quick reply. You are not.

    + +

    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

    + + diff --git a/files/en-us/mdn/contribute/where_is_everything/index.html b/files/en-us/mdn/contribute/where_is_everything/index.html new file mode 100644 index 000000000000000..78ef9b779101248 --- /dev/null +++ b/files/en-us/mdn/contribute/where_is_everything/index.html @@ -0,0 +1,34 @@ +--- +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 entire 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

    + + + +

    Other repos

    + +