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/ (opens in a new tab))
• Node.js 22+ and Bun 1+

1. 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.
2. Clone your fork with git clone https://github.com/<YOUR_USERNAME>/cup (if you use SSH, git clone git@github.com:<YOUR_USERNAME>/cup) and open your editor
3. Switch to your newly created branch (e.g. if your branch is called improve-logging, run git checkout improve-logging)
4. Run bun install in web/ and ./build.sh to set up the frontend

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 (opens in a new tab) 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!