How to Contribute to Codecademy Docs
Tags: codecademy, tutorial, github, git
Published: 2021-11-19 03:34:00

Hello, #DEVCommunity! For the past year, [Codecademy Docs](https://www.codecademy.com/resources/docs), or just "Docs", has grown into over 1,000 entries covering a variety of concepts and terms related to programming languages and frameworks. In this post, we will learn about how to contribute to Docs!

#### Table of Contents

- [What is Codecademy?](#what-is-codecademy-docs)
- [How does it work?](#how-does-it-work)
  - [Docs GitHub repo](#docs-github-repo)
  - [Answering an issue](#answering-an-issue)
- [Creating a new entry](#creating-a-new-entry) 
  - [1. Fork the Docs repo and clone locally](#1-fork-the-docs-repo-and-clone-locally)
  - [2. Create and switch into separate branch](#2-create-and-switch-into-separate-branch)
  - [3. Edit and save the file](#3-edit-and-save-the-file)
  - [4. Commit and push changes to separate branch](#4-commit-and-push-changes-to-separate-branch)
  - [5. Create pull request on GitHub](#5-create-pull-request-on-github)
  - [Using the GitHub UI](#using-the-github-ui)
- [Editing an existing entry](#editing-an-existing-entry)
  - [Handling bugs and errors](#handling-bugs-and-errors)
- [Conclusion](#conclusion)

## What is Codecademy Docs?

Docsis a free, open-contribution resource that has an ever-growing collection of entries spanning many languages and frameworks, including: 

- C++
- CSS
- HTML
- JavaScript
- React
- SQL

![Screenshot of example Docs entry.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/47fzq780hn5epptnx05t.png)

There are currently more than 1000 entries that have been submitted and edited by learners from across the world! Docs was also recently added on [Product Hunt](https://www.producthunt.com/posts/codecademy-docs) and has already amassed over 150 upvotes.

[[Back to table of contents]](#table-of-contents)

## How does it work?

Docs is built by the community and maintained by Codecademy. Every time a new/edited entry goes live, if they want, the author can be credited on the "Contributors" list for that entry.

![Screenshot of contributors list on Docs.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ve59jrh4nnvxmvmr8l28.png)

[[Back to table of contents]](#table-of-contents)

### Docs Github repo

All of the changes to Docs are housed in the [**Codecademy/docs**](https://github.com/Codecademy/docs) repo on GitHub. 

The "Pull requests" tab contains any open PRs pertaining to Docs entries.

[[Back to table of contents]](#table-of-contents)

### Answering an issue

[Issues](https://github.com/Codecademy/docs/issues) are ideally created by Docs maintainers in the "Issues" tab to request new entries, edits, or bug fixes. However, this is the place where many contributors go to pick a subject that is appealing and create entries about them.

![Screenshot of issues tab for Codecademy Docs repository on GitHub.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1asaiikwc2vcz5wnhtzy.png)

If you see an issue that you'd like to work on, select it and leave a comment on the thread. Someone from our team will reach out!

[[Back to table of contents]](#table-of-contents)

## Creating a new entry

The following sets of instructions represent two common workflows for contributing to Docs. Contributing to Docs is a great way of brushing up on [Git](https://www.codecademy.com/resources/docs/git) using the command line.

[[Back to table of contents]](#table-of-contents)

### 1. Fork the Docs repo and clone locally

To mitigate any conflicts when merging changes, we recommend that you fork the **Codecademy/docs** repo. 

![Screenshot of "Watch", "Star", and "Fork" options on Codecademy Docs repository.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ucvdgc5us7ujvp1cwii7.png)

From your forked Docs repo (or your _remote repo_), you can then clone the project onto your local machine using the repo URL (I usually go with the HTTPS one). This will create your _local repo_.

```
git clone https://github.com/github_username/docs.git
```

Before working on any new changes, always make sure sure that your forked `main` branch is even with the original `Codecademy/docs:main` branch. You do this by clicking **"Fetch Upstream"** and then **"Fetch and Merge"** on your remote repo:

![Screenshot of remote forked repository and green "Fetch and Merge" button](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sbwghq1eqfiiutq070es.png)

Then, `pull` those changes down to your local repo (make sure you're on your `main` branch):

```
git checkout main
git pull
```

[[Back to table of contents]](#table-of-contents)

### 2. Create and switch into separate branch

Another important part of contributing to the Docs repo is to **never** push changes from your forked repo's `main` branch. This is because reviewers and maintainers may want to test your changes on their own forks. However, they can't do this if the name of the branch they're pulling from is also called `main`. Therefore, do the following, always create and switch into a separate branch before editing files:

```
git checkout -b separate-branch
```

[[Back to table of contents]](#table-of-contents)

### 3. Edit and save the file

In this step, go ahead and make all the necessary changes to the file and save afterwards. When contributing to Docs, you should only work on a single entry (a single file) at a time.

[[Back to table of contents]](#table-of-contents)

### 4. Commit and push changes to separate branch

**Tip:** I run `git status` before following this step just to see which files are staged vs. un-staged for commit. 

When finished making changes, we can add (or stage) the files for commit:

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

This next part is crucial: we're gonna `push` the changes up to the branch we created in the last step.

```
git push origin separate-branch
```

This will cause a remote-equivalent of the branch to be created on GitHub and, by extension, trigger a prompt to create a new pull request. 

![Screenshot of remote, forked Codecademy Docs repository with pull request prompt.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oj8d9g3l6ngc247ai613.png)

The `origin` remote is the connection between your local repo and the 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:

```
git remote add origin https://github.com/Dusch4593/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 were 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)
```

[[Back to table of contents]](#table-of-contents)

### 5. Create pull request on GitHub

After the staged changes are committed and pushed, it is time to switch over to GitHub and finish by creating a pull request, or PR.

When we open up our forked repository, we will notice a notification that appears near the top:

![Screenshot of PR ready to be created from pushed commits](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/c9y45wrd53jnsrh2d9ae.png)

After clicking on "Compare & pull request", we will be directed to a page with a markdown editor for creating the PR:

![Screenshot of clicking "Compare & pull request" button.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/089gtt4jeyawq96dfdo3.png)

After filling out some of the provided fields and checking all the boxes (please do!) we can click "Create pull request."

Past this point, the review process can begin where as many as three reviews can take place depending on depth and how many files are involved with the PR.

[[Back to table of contents]](#table-of-contents)

#### Using the GitHub UI

Alternatively, this process can be performed entirely from GitHub's user interface (UI) on the web, no command line necessary! The following steps are outlined below:

1. Create a new PR branch on your forked repo.   ![Screenshot of creating a new PR branch on GitHub.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dmvvxkm5eyh0t2ww1oz0.png)
2. Find a place to create new content: ![Screenshot of a selecting a folder.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/91qacncuh9fpuczdv7o1.png)
3. Create and name a new file: 
![Screenshot of a new file being named.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/k14hhr0zhn7nmxtuc1pj.png)
  * Files can be made within new or existing folders as well!
4. Commit the newly-changed file: 
![Screenshot of the "Commit New File" button being clicked.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vb91md3nn5n62ntwzudh.png)
5. Finish by creating a new pull request (using step 5 under "Using Git").

[[Back to table of contents]](#table-of-contents)

## Editing an existing entry

There are two distinct methods for editing an existing Docs entry:

- By following the same steps listed in the previous section.
- By editing the file and committing the changes directly on GitHub.

For the second method, a great place to start is from a live entry on the Docs site.

![Screenshot of a live Codecademy Docs entry showcasing the "Edit this page on GitHub" link](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/a9kcczg7ky2a3gtl2m35.png)

Near the top-right corner of the page for any Docs entry is an **"Edit this page on GitHub"** link to the equivalent file on the Docs repo, ready for editing!

![Screenshot of TypeScript generics entry file in edit-mode](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xmdjedtk3pphz1hktffh.png)

After making changes, scroll down near the bottom to find a prompt for committing the changes and submitting a pull request.

![Screenshot of TypeScript entry in edit-mode with commit prompt](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/73exx84qlgib36so7ny7.png)

Inside this prompt, you can:

- Give the commit a specific name and description.
- Custom-name the separate branch that will be auto-created by the prompt.

[[Back to table of contents]](#table-of-contents)

### Handling bugs and errors

For bugs and errors, your options include:

- Reporting it by filling out [this issue form](https://github.com/Codecademy/docs/issues/new?assignees=Name+here&labels=bug&template=bug_reports.yml&title=%5BBug%2FError%5D+Subject+%3A+Entry+Name).
- Following the steps outlined earlier in the ["Editing an existing entry"](#editing-an-existing-entry) section.

[[Back to table of contents]](#table-of-contents)

## Conclusion

At this point, you will have committed/pushed your changes and submitted a pull request to be reviewed by either me or one of my colleagues. After we've approved and merged the changes, congratulations! You've just made your first contribution on Codecademy Docs!

I hope this post was help to anyone interested in building the next best documentation resource. I'm excited to have helped build this project and I hope you'll come and help us build it more!

To hear any updates with Docs, go to [#CodecademyDocs](https://twitter.com/search?q=%23CodecademyDocs&src=typed_query&f=live) on Twitter. And please feel free to leave us any feedback about Docs [here](https://docs.google.com/forms/d/e/1FAIpQLSeqwAiV8C2EjXciqTvPFI-ABxkh9iyy7HL-hnr69GrRW99MiA/viewform).

[[Back to table of contents]](#table-of-contents)