Skip to content
ScottyLabs Docs

Contributing

Contributing to CMUHousing

Thank you for your interest in contributing to CMUHousing! This guide will help you get started.

Setup Codeberg

ScottyLabs developers must follow this guide to setup their codeberg in order to commit. CMUHousing developers also should add themselves to the cmuhousing team using these instructions. This allows your commits to be verified and signed.

How to Contribute

  1. Fork the repository or create a new branch if you have write access

  2. Create a new branch from main with a descriptive name:

    Terminal window
    git checkout -b your-feature-name
    # or
    git checkout -b bug-description

  3. Make your changes following the code style and conventions

  4. Test your changes locally by running the project. See README.md for more instructions on running the project.

  5. Commit using conventional commits (see below)

    Terminal window
    git add .
    # then
    git commit -m "Your commit message"

  6. Push to your fork or branch

    Terminal window
    # if first branch push
    git push --set-upstream origin your-branch-name
    

    # otherwise
    git push

  7. Open a Pull Request with a clear description of your changes. You can do this by going to the link provided in the push terminal response or by visiting your branch on GitHub.

Conventional Commits

This project follows Conventional Commits.

Examples:

  • feat: add course search by instructor
  • fix: resolve dining hall location formatting issue
  • docs: update README installation steps
  • refactor: simplify embed pagination logic
  • chore: update dependencies to latest versions
  • style: format code with biome

Code Editor Setup

We recommend using VSCode, and the following setup guide will assume you are using VSCode.

Recommended VSCode extensions:

You will also need git installed.

Local Development

Prerequisites: devenv and direnv.

Terminal window
cd housing
direnv allow
devenv up   # starts the frontend dev server on port 3000

If secretspec complains about the vault provider locally, use:

Terminal window
SECRETSPEC_PROVIDER=dotenv://.env devenv shell

Before Submitting

Before you commit and open a pull request, make sure to:

  • Run npm run lint in apps/frontend and fix any errors/warnings
  • Run npm run format from the repo root to format your code
  • Test locally with your changes (devenv up or npm run dev in apps/frontend)
  • Ensure your commits follow conventional commit format
  • Update documentation if you added/changed features

Pull Request Guidelines

  • Keep PRs focused - One feature or fix per pull request
  • Write clear descriptions - Explain what changed and why
  • Reference related issues - Use “Fixes #123” or “Closes #456” if applicable
  • Be responsive - Address review feedback promptly

Project Priorities & Planning

To understand current priorities, roadmap, and ongoing work:

  • Visit the CMUHousing Development project
    • Pick an issue from the board and assign it to yourself.
    • Use Priority and Size labels to choose based on what you can handle in a timely fashion.
  • If you cannot access the board, ask a maintainer to add you to the ScottyLabs organization.

Need Help?

If you have questions or need help:

  • Check existing issues and pull requests for similar questions
  • Check resources below for help on issue subject
  • Reach out to leadership with questions

Project Resources

Points of Contact

  • Project Lead: Nikhil (@ecstaticpilot)
  • Advisors: Max (@tentype) and John (@gostmeaper)
  • Outreach/ResEd Contact: John (@gostmeaper)
  • Senate Contact: Sanjeev (@blender1778)
  • DevOps: Ryan (@thesuperrl)

Remember to follow conventional committing guidelines while contributing!