Contributing

System Requirements

Local Development

  1. Clone the repository and open freeCodeCampOS/example as a new workspace in VSCode.

  2. Install dependencies and build the project:

    bun install
bun run build

  3. Run the development server:

    cargo run --bin freecodecamp-server

  4. In a separate terminal, run the client in development mode:

    cd client && bun run dev

    The client will be available at http://localhost:5173.

Common Tasks

# Run all tests
cargo test --all

# Check formatting
cargo fmt --all -- --check

# Fix formatting
cargo fmt --all

# Run linter
cargo clippy --all -- -D warnings

# Build optimized binaries
cargo build --release --all

# Build client assets
cd client && bun run build

Environment Variables

RUST_LOG=info               # Log level (debug, info, warn, error)
PORT=8080                   # Server port (default: 8080)
CONFIG_PATH=./conf.json     # Path to configuration file

Repository Layout

cli/          # create-freecodecamp-os-app CLI tool
client/       # React frontend
config/       # Shared types and configuration
docs/         # Documentation (this site)
example/      # Example curriculum used for development
parser/       # Curriculum markdown parser
runner/       # Test execution engine
server/       # Axum HTTP server

Gitpod

Open in Gitpod

Opening a Pull Request

  1. Fork the repository
  2. Push your changes to your fork
  3. Open a pull request with the recommended style

Commit Message

<type>(<scope>): <description>

Example

feat(docs): add contributing.md

Pull Request Title

<type>(<scope>): <description>

Example

feat(docs): add contributing.md

Pull Request Body

Answer the following questions:

  • What does this pull request do?
  • How should this be manually tested?
  • Any background context you want to provide?
  • What are the relevant issues?
  • Screenshots (if appropriate)

Types

  • fix
  • feat
  • refactor
  • chore

Scopes

Any top-level directory or config file. Changing a package should have a scope of dep or deps.

Documentation

This documentation is built using mdBook. Read their documentation to install the latest version.

Also, the documentation uses mdbook-admonish:

cargo install mdbook-admonish

Serve the Documentation

cd docs
mdbook serve

This will spin up a local server at http://localhost:3000 with hot-reloading.

Build the Documentation

cd docs
mdbook build

CLI (create-freecodecamp-os-app)

The CLI is written in Rust and is located in the cli directory.

Development

cd cli
cargo run

Flight Manual

Release

Releases are done manually through the GitHub Actions.

Making a Release

In the Actions tab, select the Publish to npm workflow. Then, select Run workflow.