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.
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.
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.
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.
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.
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.
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.
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.
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:
- Fork the repository and create your branch from
master. - Run
yarnin the root of the project that you are working on (/website,/export, or/packages/nusmoderator). - 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).
- Ensure the test suite passes (
yarn test). Tip:yarn test:watchis helpful in development. - Run
yarn run ciwhich 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 viayarn run lint,yarn testandyarn run buildrespectively. - There might be project-specific contribution details. Please read the README of the respective projects.
Contributing to open source projects you enjoy using and want to make better is an amazing way to give back to the community and improve your skills as a developer! Here's a non-exhaustive list of other NUS-related open source projects you might want to get your hands dirty with:
- CourseRekt - A tool for visualising past vacancy reports to help you strategise for course registration.
- NUS Timetable Optimizer - An application that helps students optimize their timetables for the best possible schedule.
- LoMiNUS - An app which helps Canvas and the now-defunct LumiNUS download their files and keep them in sync.
- CATcher - An issue management tool for software engineering project teams.
- MarkBind - A tool for generating static websites from Markdown documents.
- PowerPointLabs - A PowerPoint add-in that provides advanced features for creating presentations.
- RepoSense - A tool that generates contribution summaries for Git repositories.
- TEAMMATES - A feedback management tool for education.
Good luck, and happy hacking!
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.
By contributing to NUSMods, you agree that your contributions will be licensed under its MIT license.