--- title: "How to work on CodeRoad" --- > Documentation Index > Fetch the complete documentation index at: https://contribute.freecodecamp.org/llms.txt > Use this file to discover all available pages before exploring further. # How to work on CodeRoad :::tip You'll need this guide if you're contributing to tutorials that use the CodeRoad VS Code extension. If you're working on the main freeCodeCamp curriculum or other areas, you can skip this guide. ::: This page describes how to contribute to the freeCodeCamp tutorials and projects that are completed using the CodeRoad VS Code extension. ## How the Tutorials Work Each of the freeCodeCamp tutorials that use CodeRoad has its own repo under the freeCodeCamp GitHub organization. They all start with `learn-`. For example, `https://github.com/freeCodeCamp/learn-bash-by-building-a-boilerplate/`. Each tutorial repo has a `main` branch and a "version" branch, e.g. `v1.0.0`. The two main files on the `main` branch are `TUTORIAL.md` and `coderoad.yaml`. `TUTORIAL.md` contains all the instructions, hints, titles, and so on, for the tutorial. `coderoad.yaml` contains instructions for CodeRoad, such as what commands to run and when, what files to watch for changes, and what version branch to use for the steps. The "version" branch contains the commits that will be loaded on each step of a tutorial. The commit messages on this branch have to be specific. The first commit needs `INIT` for its message and contains all the files to load before the first lesson. Step setup commit messages must match the step number in `TUTORIAL.md` from the `main` branch. For example, the commit with the message `10.1` will be loaded when a user goes to step `10.1`. In order to make changes to commits on a version branch, you would need to rebase and edit the commits you want to change. This will rewrite the Git history, so we cannot accept PRs to these types of branches. Once a version branch is on the freeCodeCamp repo, it should never change. :::caution Never make or push changes to a version branch that is on one of the freeCodeCamp repos. Always create a new one ::: ## How to Contribute ### Prerequisites Use Node.js 20 for the [CodeRoad CLI tools](https://www.npmjs.com/package/@coderoad/cli). CLI version `0.9.3` fails to start on Node.js 22 and 24. See the [CodeRoad CLI compatibility issue](https://github.com/coderoad/coderoad-cli/issues/109). If you use nvm, switch to Node.js 20, then install the CLI: ```bash nvm install 20 nvm use 20 npm install -g @coderoad/cli coderoad --version ``` ### Set Up the Tutorial Repository Fork the tutorial repository and clone your fork. In the commands below, `origin` refers to your fork and `upstream` refers to the freeCodeCamp repository. From your clone, add the upstream remote if it does not already exist, replacing `TUTORIAL_REPO` with the repository name: ```bash git remote add upstream https://github.com/freeCodeCamp/TUTORIAL_REPO.git ``` Before starting work, fetch the upstream branches and update `main`: ```bash git fetch upstream git checkout main git merge --ff-only upstream/main ``` Read `config.repo.branch` in `coderoad.yaml` on the updated `main` branch to find the version branch the tutorial uses. Replace `vX.X.X` in the instructions below with that branch name. ### Working on `main` This set of instructions is for PRs that only make minor changes on `main` to **existing lessons**. That mainly consists of typo, grammar, hint, and instructional changes or fixes in the `TUTORIAL.md` file. These minor changes do not require a new version branch. For everything else, including adding or deleting lessons, follow the [working on a version branch instructions](#working-on-version-branch). :::note These changes will use the existing version branch. If they are substantial, feel free to add them to `CHANGELOG.md`. Most of the time, a good commit message should work ::: You never need to modify the `tutorial.json` file directly. That will be created with the CLI tools. If you are only making minor changes like fixing a typo or grammatical error, you don't have to test your changes. Follow these instructions to make a PR, keeping in mind that instructions usually use the lessons around them for context: - Create a local copy of the version branch specified by `config.repo.branch` with `git branch vX.X.X upstream/vX.X.X`, if it does not already exist. You do not need to check this branch out; it just needs to exist. - Create and checkout a new branch off of `main` - Make **and commit** your changes. Reminder: You don't need to change anything in the `tutorial.json` file. You likely only need to make changes to `TUTORIAL.md` - Run `coderoad build` to recreate the `tutorial.json` file - Commit the changes with `update json` as the message - Make a PR ### Testing Changes on `main` If you want to test your changes to `main` after using the above instructions, follow these instructions: - Follow the instructions on the [rdb-alpha repo](https://github.com/freeCodeCamp/rdb-alpha) to run a container - Start the tutorial using the `tutorial.json` file on the new branch ### Reviewing PRs to `main` If reviewing a PR that only changes `main` with instructional or grammar issues as described above, the changes in `TUTORIAL.md` should match the changes in `tutorial.json`. The `tutorial.json` file should not have changes to commit hashes, or step/level ids. Startup or level commands or file watchers likely should not be changed either. There are exceptions if there's an issue with a step, but they should be treated with more caution. Also, keep in mind that instructions usually use the lessons around them for context, so make sure they make sense. ### Working on Version Branch :::caution Reminder: Never make or push changes to a version branch that is on one of the freeCodeCamp repos. Always create a new one ::: There's no easy way to see exactly what changed between version branches since the Git history will be rewritten. Accepting new version branches to use will need to be done with careful consideration and testing. These instructions are for changing anything on a "version" branch, such as tests, test text, reset files, adding and deleting steps, among other things. Follow these instructions to create a new version: - Check out the version branch specified by `config.repo.branch` with `git checkout -b vX.X.X upstream/vX.X.X`. If it already exists locally, use `git checkout vX.X.X`. - Create a new branch off of that, incrementing the version, with `git checkout -b vX.X.Y` - Make your changes to the version branch. See more info in the [CodeRoad Documentation](https://coderoad.github.io/docs/edit-tutorial) for how to work with tutorials - Push the new branch to your fork with `git push -u origin vX.X.Y` - Checkout the `main` branch - Create a new branch off `main`. e.g. `feat/version-X.X.Y` - Change `config.repo.uri` in `coderoad.yaml` to your fork of the repo. This is so you and reviewers can test it before pushing it to the freeCodeCamp repo. Set `version` to `X.X.Y` and `config.repo.branch` to `vX.X.Y`. Add your changes for the new version to `CHANGELOG.md`. Make any other changes you need. - Commit your changes with the message `feat: release version X.X.Y - ` - Run `coderoad build` to create a new `tutorial.json` file - Add and commit the file - Push the changes to your fork - Test your changes following the [testing instructions below](#testing-changes-to-a-version-branch). Make any additional changes and commit them as you just did, or, if you are satisfied, follow the rest of the instructions - Make a PR to `main` using your new `feat/version-X.X.Y` branch. Give it a title of `version X.X.Y ready for review`. This will not be merged, it is just to let reviewers know that there is a new version ready - Leave it here for reviewers ### Testing Changes to a Version Branch - Follow the instructions on the [rdb-alpha repo](https://github.com/freeCodeCamp/rdb-alpha) to run a container - Start the tutorial using the `tutorial.json` file on whatever fork the changes are on. Make sure to use the file on the `feat/version-X.X.Y` branch and not the `main` branch ### Pushing a New Version Before pushing a new version, view the new `feat/version-X.X.Y` branch on the user's fork. Make sure there are additions to `CHANGELOG.md` that include the new changes, and that `version` is `X.X.Y` and `config.repo.branch` is `vX.X.Y` in `coderoad.yaml`. If you have write access to the freeCodeCamp repo, have verified the `CHANGELOG` and `coderoad.yaml` files, have tested the changes using the instructions above, and want to push a new version of a tutorial: :::caution Reminder: Never make or push changes to a version branch that is on one of the freeCodeCamp repos. Always create a new one ::: - If you don't have a remote to where the new changes exist, create a remote to the user's fork with `git remote add ` - Fetch the new branches with `git fetch ` - Delete any **local** branches that share a name with the new branches. Likely named either `vX.X.Y` or `feat/version-X.X.Y` - Checkout the new version branch with `git checkout -b vX.X.Y /vX.X.Y` - Push the new version branch to the freeCodeCamp repo with `git push -u upstream vX.X.Y`. You need to push the new branch before you update `main` with the new `tutorial.json` file - Checkout the users branch that will be merged into `main` with `git checkout -b feat/version-X.X.Y /feat/version-X.X.Y` - Change `config.repo.uri` in `coderoad.yaml` back to the freeCodeCamp repo - Add and commit the changes - Run `coderoad build` to create the new `tutorial.json` file - Add and commit the file - Push the changes to your fork with `git push -u origin feat/version-X.X.Y` - Make a PR to `main` on the freeCodeCamp repo - If you are satisfied, merge it or leave it and ask for a review from someone - After the PR is merged, open the tutorial by following the instructions on the [rdb-alpha repo](https://github.com/freeCodeCamp/rdb-alpha) to make sure it's loading properly, and that you can get through a few steps - Finally, if any PRs for this version exist, close them ### How to Revert to a Previous Version - Create a new branch off of the latest `main` with `git checkout -b revert/to-version-X.X.X` - Revert all commits on this branch up to and including the commit of the version after the one you want to revert to. For example, you may have commits that look like this: ``` fix: typo release: version 1.0.1 fix: typo release: version 1.0.0 ``` If you want to revert to v1.0.0, revert all the commits from `release: version 1.0.1` and after - Create a PR. Give it a title of `revert: to version X.X.X` Source: https://contribute.freecodecamp.org/how-to-work-on-tutorials-that-use-coderoad/index.mdx