Creating a pull request and revisions

The last and most important aspect of contributing (after creating the entry itself) is to create a pull request for it on the main repository (repo). This allows the maintainers to provide you with feedback on your entry to polish it and make it the best possible contribution to Docs. This all leads up to merging your contribution into the Docs repo.

Commit the changes on the separate branch

Once you’ve made edits you are happy with, it is time to commit those changes to the new branch you created earlier. (Remember not to make changes to your main branch.) To see what files are staged vs. unstaged for commit, you can run git status.

To stage your file(s) for commit you can run git add followed by a space-delimited list of the files. You can also run git add . to stage all the unstaged changes. (But be sure that git status isn’t showing you unexpected changes.)

Lastly you run git commit -m followed by a summary of the change in double quotes. (If you run git commit by itself, it will prompt you for a description.)

git add <space-separated list of files here>
git commit -m "brief summary of changes."

Push your changes on the separate branch

You now have the changes committed to the local repo. Now the next step is to get those changes uploaded to GitHub so we can make a pull request. We do that with a push to the separate branch we created earlier.

In order to do this we need remotes set up to connect to the repos on GitHub. The origin remote is important. It is the connection between your local repo and your remote repo. It can be set with the git remote add command. It is also recommended that you set up an upstream remote that points to the base Codecademy/docs repo itself:

git remote add origin https://github.com/github_username/docs.git
git remote add upstream https://github.com/Codecademy/docs.git

The git remote -v command can then be run to check that the remotes are set up correctly:

git remote -v
origin  https://github.com/github_username/docs.git (fetch)
origin  https://github.com/github_username/docs.git (push)
upstream https://github.com/Codecademy/docs.git (fetch)
upstream https://github.com/Codecademy/docs.git (pull)

Then you can run the following to push your commits up to your remote repo on GitHub:

git push origin branch-name

Where branch-name is the name of the separate branch we created earlier. This will create a remote-equivalent of the branch to be created (or updated) on GitHub. It will also trigger a prompt to create a new pull request on GitHub’s User Interface (UI).

Using the GitHub UI

If you’re using GitHub’s UI, you can start from step 1. Otherwise, continue to step 2.

To commit your changes using GitHub, you would commit the created file to the feature branch that you created for your issue.

1. Commit the newly-changed file:

2. Create a pull request You’ll want to create a pull request (PR) so the maintainers can see the changes you want to make on the main Docs repo. After pushing your file to your forked repo via the command line, or after committing your file via the GitHub UI, when we open up our forked or original repo on GitHub, we will notice a notification that appears near the top:

3. Click on “Compare & pull request” and be redirected to a page with a markdown editor for creating the PR.

4. For the title, enter something that describes the topic and concept, or topic, concept and term of the entry this PR is for. Add a description and type of change, and check all the boxes for your entry. Then click “Create pull request.”

Revise your entry

Once you’ve created a pull request you’ll be able to see it listed on the pull requests tab on the main Docs Repo. It’s here that you will see the maintainers comment on and review your work. Often you will see a review where a maintainer requests changes to your entry, these will be in a list of comments under the review and generally come in one of two flavors.

1. A general comment describing a specific change or changes that require rewriting part of the entry.

2. A suggestion of a line edit that shows a box labeled “suggested change” that quotes your entry with specific edits to the line in question.

With this feedback you can go back and edit your entry either via your local repository and the command line, or through the GitHub UI. Every new commit you make to the branch will be visible in the PR. As you address comments, it is a good idea to click on the “Resolve Conversation” button which helps keep track of the edits you’re making.

For comments with a “suggested change”, there’s a shortcut to commit the requested edits. Under the suggested change is a button that says “commit suggestion”. Clicking on that will pop up a box where you can optionally edit the description for the commit, then automatically commit the suggested change and resolve the conversation.

Once you make the edits, it is a good idea to tag the reviewer in a comment so they know you’ve completed them, so they can come back and review your edits in a timely manner. They will then either approve your PR or suggest more edits. Once two or more maintainers approve of your PR, one of the maintainers will merge your PR into the repo and your contribution to Docs will be live on the site.