import { Steps } from "nextra/components";

# Contributing

First of all, thanks for taking time to contribute to Cup! This guide will help you set up a development environment and make your first contribution.

## Setting up a development environment

Requirements:

- A computer running Linux
- Rust (usually installed from https://rustup.rs/)
- Node.js 22+ and Bun 1+

<Steps>
### Fork the repository
This is where you'll be pushing your changes before you create a pull request. Make sure to _create a new branch_ for your changes.
### Clone your fork
```bash
git clone https://github.com/<YOUR_USERNAME>/cup
```
If you use SSH:
```bash
git clone git@github.com:<YOUR_USERNAME>/cup`)
```
### Switch to your newly created branch (e.g. if your branch is called `improve-logging`, run `git checkout improve-logging`)
### Set up the frontend
```bash
$ cd web
$ bun install
$ cd ..
$ ./build.sh
```
</Steps>

You're ready to go!

## Project architecture

Cup can be run in 2 modes: CLI and server.

All CLI specific functionality is located in `src/formatting.rs` and some other files in functions prefixed with `#[cfg(feature = "cli")]`.

All server specific functionality is located in `src/server.rs` and `web/`.

## Important notes

- When making any changes, always make sure to write optimize your code for:

  - Performance: You should always benchmark Cup before making changes and after your changes to make sure there is none (or a very small) difference in time. Profiling old and new code is also good.
  - Readability: Include comments describing any new functions you create, give descriptive names to variables and when making a design decision or a compromise, ALWAYS include a comment explaining what you did and why.

- If you plan on developing the frontend without making backend changes, it is highly recommended to run `cup serve` in the background and start the frontend in development mode from `web/` with `bun dev`.

- If you make changes to the frontend, always remember to prefix your build command with the `build.sh` script which takes care of rebuilding the frontend. For example: `./build.sh cargo build -r`

- When adding new features to Cup (e.g. configuration options), make sure to update the documentation (located in `docs/`). Refer to other pages in the documentation, or to the [official docs](https://nextra.site) for any questions you may have. The docs use `pnpm` as their package manager.

- If you need help with finishing something (e.g. you've made some commits and need help with writing docs, you want some feedback about a design decision, etc.), you can open a draft PR and ask for help there.

## Submitting a PR

To have your changes included in Cup, you will need to create a pull request.

Before doing so, please make sure you have run `cargo clippy` and resolved all warnings related to your changes and have formatted your code with `cargo fmt`. This ensures Cup's codebase is consistent and uses good practices for code.

After you're done with that, commit your changes and push them to your branch.

Next, open your fork on Github and create a pull request. Make sure to include the changes you made, which issues it addresses (if any) and any other info you think is important.

Happy contributing!
