How to work on CodeRoad

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.

How to Contribute

Prerequisites

Use Node.js 20 for the CodeRoad CLI tools. CLI version 0.9.3 fails to start on Node.js 22 and 24. See the CodeRoad CLI compatibility issue.

If you use nvm, switch to Node.js 20, then install the CLI:

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:

git remote add upstream https://github.com/freeCodeCamp/TUTORIAL_REPO.git

Before starting work, fetch the upstream branches and update main:

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.

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

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 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 - <optional description>
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. 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 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:

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 <remote> <users_fork_url>
Fetch the new branches with git fetch <remote>
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 <remote>/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 <remote>/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 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