Skip to content

Latest commit

聽

History

History
81 lines (47 loc) 路 6.05 KB

CONTRIBUTING.md

File metadata and controls

81 lines (47 loc) 路 6.05 KB
Raw

Contributing

Are you here to make NUSMods better? Awesome!

There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code for NUSMods. Every small bit helps us out immensely.

How to use this guide

If you're a beginner, lots of technical terms in this guide may be foreign to you. Don't worry, we were once in your shoes too. Take it one step at a time and do some research. As always, get in touch with us if you need any help.

Experienced developers may choose to skip this guide. Our development process is very similar to most other open source projects.

Along the way, if you find details that are missing or wrong, or you would like to improve this guide, feel free to submit a pull request.

Technical Prerequisites

These are the tools that keep NUSMods ticking. It would be helpful to have a basic understanding of these technologies.

  • Git is the software we use for collaboration. Atlassian's Git Tutorials is a very comprehensive resource.
  • JavaScript is the programming language NUSMods uses. Mozilla's Javascript Guide is a good place to start to learn the language.
  • TypeScript is a language superset of JavaScript, i.e. it's JavaScript but with more features. Its biggest additional feature is types, which help us understand the code better and reduce bugs. Refer to the TypeScript Documentation to learn more.

Repo Overview

This repository contains all the code that NUSMods uses. It may seem overwhelming, but each folder is self contained.

Folder Purpose
/website Houses the code for the https://nusmods.com website
/scrapers Scripts that download module and timetable data from NUS to our server
/export Contains a service which allows users to download the timetable as images and PDFs
/packages Helper JavaScript libraries that can be reused by projects outside NUSMods

Tip: Pick an area you're interested in, and just focus on it. It is not necessary to know all the code to contribute.

Development Tools

You should have Node.js version 18 or above (use Node 18 LTS or lts/hydrogen if possible) and Yarn version 1.2.0 or above. We recommend using fnm to manage your Node versions.

Proposing a Change

If you intend to make any non-trivial changes to the UI or implementation in any of the projects, we recommend first filing an issue. This lets us reach an agreement on your proposal before you put significant effort into it.

If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.

Branch Organization

We practice trunk-based development and do deployments from the master branch, which is the only stable and long-lived branch around. We will do our best to keep the master branch in good shape, with tests passing at all times.

Your First Pull Request

Working on your first Pull Request? You can learn how from this free video series:

How to Contribute to an Open Source Project on GitHub

To help you get your feet wet and get you familiar with our contribution process, we have a list of good first issues that contain bugs/enhancements that have a relatively limited scope. This is a great place to get started.

If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don't accidentally duplicate your effort.

If somebody claims an issue but doesn't follow up for more than two weeks, it's fine to take over it but you should still leave a comment.

Submit a Pull Request

The core team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation.

Before submitting a pull request, please make sure the following is done:

  1. Fork the repository and create your branch from master.
  2. Run yarn in the root of the project that you are working on (/website, /export, or /packages/nusmoderator).
  3. If you've fixed a bug or added code that should be tested, add tests! We ask that you write tests if your feature contains non-trivial logic. Tests can be omitted for minor layout or stylistic changes (or simply generate a snapshot).
  4. Ensure the test suite passes (yarn test). Tip: yarn test:watch is helpful in development.
  5. Run yarn run ci which runs the linting, testing and building steps. This is the command that is run on our CI system. There should not be errors shown. Alternatively, you can run the linting, testing and building step separately via yarn run lint, yarn test and yarn run build respectively.
  6. There might be project-specific contribution details. Please read the README of the respective projects.

Code of Conduct

We have adopted Facebook's Code of Conduct that we expect project participants to adhere to. Kindly read the full text to understand what actions will and will not be tolerated.

License

By contributing to NUSMods, you agree that your contributions will be licensed under its MIT license.