Skip to content

Latest commit

 

History

History
167 lines (110 loc) · 13.2 KB

CONTRIBUTING.md

File metadata and controls

167 lines (110 loc) · 13.2 KB
Raw

Docs: Contribution Guide 👩🏻‍💻👨🏾‍💻👩🏼‍💻

Contribute to Docs! Please see our updated Contribution Guide that provides a step-by-step video and text guide on how you can make an impact through Docs. 🌠

Welcome to the Docs GitHub repo!

We are an inclusive and passionate team of technologists and life-long learners around the world, building free programming resources for a better tomorrow. For newcomers, contributing to an open-source project for the first time can be intimidating and overwhelming. Perhaps you’re a code newbie, or maybe you’ve been tinkering for years but haven’t found that special project yet.

Good news, you are in the right place! Docs is the perfect open-contribution project for you to get started. Every part of Docs content (entries, documentation, and translations) is written by amazing creative folks like yourself.

Thanks for your interest; we'd love to have you contribute. 💖

How do I contribute?

There are many ways to contribute to Docs:

If you're new to Docs and contributing for the first time, it is recommended that you visit the Issues section and ask to be assigned to an open issue that interests you. Otherwise, feel free to submit a PR by creating a new branch in your fork to create a new entry or edit an existing one.

How do I claim an Issue?

Becoming an assignee to an issue follows this workflow:

  1. Comment on a thread for an open issue that you're interested in being assigned to (e.g., Issue #1026).
  2. Await 2-3 days for a maintainer's response to be assigned an issue. If assigned, start working on a PR. If not yet assigned, continue steps 1 and 2 until assigned an issue.
  3. If a PR has not been opened in 2 weeks for the issue, the issue may be reassigned to another contributor. Maintainers will do their best to notify contributors by tagging their GitHub handle along the issue thread every 5-7 days.
  4. Please note that you aren't allowed to claim more than 3 open issues (issues without a PR) at a time.

How do I submit a Pull Request (PR)?

Contributing follows this workflow:

  1. Fork this project repository: A red stencil outlining the "Fork" link for the Codecademy Docs repo
  2. Clone the forked repository to your computer. One option is using the HTTPS URL: git clone https://github.com/github_username/docs.git
  3. Create and switch into a new branch.
  4. Edit or create an entry and commit the changes.
  5. Make a PR to merge your fork with this repo: Red arrow on the Codecademy Docs repo pointing at a pop-up link for creating a new pull request

If you haven't gone through this workflow before, you can check out this GitHub tutorial (highly recommend) or this YouTube video to learn about how to make a PR from a fork using Git.

Alternatively, if you'd prefer to work directly on GitHub, you can follow the instructions in that video up to 1:18. After forking this repo, you can create your entry in your fork using the website's user interface and make a PR by pressing this handy button:

Code block with Codebyte tags

If you are uncomfortable using Git, you can also check out this YouTube video to do this all using the GitHub Desktop app.

Note: There should be some noticeable activity (such as new commits or comments) within the PR branch every 2-3 days.

How can I test my changes before submitting a PR?

There are a few tools you'll need to install in order to run our test suites locally:

  • yarn: we use yarn to manage dependencies (instead of npm)
  • node 16.0.0 (or newer): the tests will likely run on earlier versions of node, but if you'd like your changes to be formatted automatically when you commit then you will need to be on node 16 or greater
  • nvm: while not required, we recommend using nvm to manage multiple versions of node on the same machine

With everything installed, in the repository root (whatever directory contains the package.json file), you can run:

Note: If you use npm instead of yarn, it is fine to do so with the commands described below.

  • yarn format:verify and yarn lint:md to validate markdown file contents
  • yarn test to validate content/ directory structure

I submitted a PR, but tests are failing. How do I fix them?

Here are some common issues and resolutions:

  • The verify_formatting is failing
    • Run yarn format path/to/markdown/file.md or yarn format:all and commit the results.
  • The verify_lint is failing
    • Same as above.
    • If verify_lint is still failing, running yarn lint locally should let you know what needs to be changed by hand.
  • The test is failing
    • Ensure any new markdown files have a Title and Description defined in their metadata.
    • Ensure any new markdown files only contain alphanumerics and dashes in their file names and have the same name as their parent directory.
    • If that looks okay, running yarn test locally should let you know what the issue is.

What do I need to do before creating new entries?

Before creating new entries, poke around the /content folder. This is where all the content is stored.

Please read through the following in the /documentation folder. In these links, you'll find a write-up of our standards for content and style:

The following are templates for creating your new entries:

Template GitHub Example Docs Example
Concept Entry Template lists.md (Raw) Lists
Term Entry Template append.md (Raw) Append
Topic Entry Template sql.md (Raw) SQL

Codecademy Username

As a Docs contributor, you have the opportunity to have your Codecademy username displayed on the side of the entry!

If you wish to have your Codecademy profile listed in the entry, before making the PR, make sure that your Codecademy user profile and your GitHub are linked, and that your Codecademy profile is set to public. You can stay anonymous by not linking them.

To link your Codecademy user profile to GitHub:

  1. Log out of Codecademy.
  2. Make sure that the email address associated with your Codecademy account is the primary email associated with your GitHub account.
  3. Go to the Codecademy login page.
  4. Select the GitHub icon under "Or log in using:"
  5. Proceed through the OAuth process.

Any requirements for a Pull Request (PR)?

  • Before making a PR, make sure you pushed your changes from a branch other than main.
  • Name the new branch after the changes are pushed to the PR.
  • Keep your PRs byte-sized. No more than 3 new entries per PR! And do not have more than 3 PRs open in a two week period!
  • All contributors must sign the Contributor License Agreement (CLA) when contributing for the first time.
  • All required status checks are expected to pass in each PR.
  • PRs will be marked as invalid if there is no consistent activity within a 2-week period on the contributor's part and content does not meet or pass standard formatting, quality, and plagiarism checks.
  • We require at least two round of reviews from the content team members. Make sure to make the changes after each round.
  • Requested changes must be resolved before merging.
  • Your entry will be deployed within the hour after it's merged!
  • Refer to the Codecademy Markdown Style Guide.

What do we check for?

  • Technical accuracy
  • Formatting standards
  • Typos/bugs
  • Plagiarism

What is the policy for using generative AI?

We will not accept entries that were exclusively generated through an AI tool. We have this policy because:

  • AI-generated content is often confidently incorrect, leading to the spread of inaccurate or misleading information.
  • We provide authorship credit for submissions, and to submit AI-generated work under one's own name would be a violation of our plagiarism policy.
  • Docs is an educational space for people to learn how to write effective technical documentation. Using generative AI, at this point, negatively impacts that desired learning goal.

How do we update a PR branch?

To keep your PR branch up to date, navigate to the branch on your fork. Then press Fetch upstream and Fetch and merge.

Image of where the Fetch upstream button

Image of the Fetch and merge button

The following Git commands can be run on the command line:

git remote add upstream https://github.com/Codecademy/docs.git
git fetch upstream
git rebase upstream main
git push

Additional Resources

Remember, if you ever have any questions at all, we're always here to help in the Codecademy Forums and Codecademy Discord.

If you find any bugs or errors in the content, feel free to file an issue here! 🖖