Getting my feet wet — my experience with open-source and NUSMods

Zames Chua
May 30, 2017 · 8 min read

Update: This post is outdated with the introduction of NUSMods R.
The NUSMods team is super helpful and if you need any help with understanding the codebase, be sure to hit up the @nusmods Telegram group!


Ever since I started learning programming, I had been hearing a lot about open-source. I thought the idea of open-source was stupid. Why would anyone invest their time in something that doesn’t directly help them make more money or save more time?

However, my opinions changed greatly after I started working on NUSMods. I learnt so much in such a short span of time. Many of my friends who use NUSMods daily were also surprised to learn that I was a contributor to NUSMods. Today, I take pride in contributing to code for the community.

When I first started working on open-source, everything seemed so daunting. I hope that by documenting my progress, I’ll be able to help beginners who are on the same path as me.


What in the world is NUSMods?

NUSMods in its current state

Zhi An, who’s a frequent contributor to NUSMods, introduced me to the project at the start of 2017. He told me that the NUSMods core team were porting the old NUSMods page to a new v3 version. I was excited to find out what the code for NUSMods looked like, since I use NUSMods on a daily basis.

NUSMods v3

Table of contents

  1. Setting up the development environment
  2. Understanding the project structure
  3. Can we finally start coding now?

Understanding the stack

I had written simple HTML, CSS and Javascript code before, but the whole Node.js infrastructure was foreign to me. One of the greatest challenges I faced was to understand how the pieces in the infrastructure were related to one another. As such, I’ll try my best to summarise what I’ve learnt.

What is Node.js?

Node.js is currently being used by many companies like Netflix, PayPal, and even Medium!

Check out this discussion if you’re interested in reading more about Node.js.

What is React.js?

It is open-sourced and being maintained by Facebook. What does this mean for us developers? Sometimes having great support for a framework means that it will be easier to find a solution when one runs into bugs, or be more sure that the time invested in learning the technology is going to be worth it since it is here to stay (at least for the next few years).

What is a package / npm / Yarn?

npm makes it really easy to install and manage these packages. For example, installing react into a project is as easy as

> npm install react

Sometimes when projects get large, it may become difficult to install and manage all these packages, and setting up the development environment can get very painful.

Yarn is a relatively new package manager developed at Facebook that aims to solve some quirks that npm has.

What is Git / GitHub?

In essence, Git is a version control system for software. You can think of Git as ‘save points’ for code. When writing code, it is important to make commits (save points) so that we can get back to them later when we make a mistake down the road later. There are many more uses to Git, which you can learn about here.

GitHub is a tool that allows one to host their repositories in the cloud, and lets developers to collaborate with one another on a piece of software. I’ll be talking more about GitHub in the next part of this series.

Setting up the development environment

Following the instructions on the v3 github repositary page, I installed the various software required.

  1. Install Git
  2. Install Node.js
  3. Install Yarn

Next, I had to clone the NUSMods repository onto my desktop via the command line.

Note that the Windows Command Prompt is very different from Linux / Apple Bash shells. I use Windows, but you can try referring to this short command line guide for other systems if you are unsure of how to use the command line.

The Command Line and Git are very powerful tools so be sure to take some time to learn them well!

> git clone https://github.com/nusmodifications/nusmods.git
Cloning NUSMods to my desktop via the Windows Command

This clones a copy of the NUSMods files to my desktop

Remember the Yarn tool that we talked about just now? We’re going to use it to retrieve the dependencies (packages) for NUSMods.

> yarn> yarn run build:dll # Do this whenever you update dependencies or change vendor bundle> yarn start

Cool, navigating to http://localhost:8080/ in the browser, we can now find a copy of NUSMods running on the local server.

http://localhost:8080/

Understanding the project structure

When you’re ready, head to /nusmods/v3/src. We’ll focus on this part of the source code first to understand how the code is structured..

NUSMods project structure

It may be very daunting for someone new to the code to understand where all the various files are. For me, I do these to help myself understand the code better:

  1. Play around with the app. For example, it will be more obvious that utils/modules-search.js carries the code for the module search bar after becoming more familiar with the app. In fact, this is pretty easy for me since I use NUSMods on a daily basis.
  2. Learn the stack well. NUSMods uses the React-Redux-Webpack stack, which has certain conventions in place that programmers try to follow, in order to make their code easier to understand. There are several good guides online that will take a significant amount of time to go through, but I promise that it will be worthwhile.

Can we finally start coding now?

Creating a new button

Head to v3/src/js/views/AppContainer.jsx

There we see the code the code that holds our navigation bar. Note that some understanding of HTML is required for this part. Take some time to get familiar with how React jsx code is structured as well.

/v3/src/js/views/AppContainer.jsx

Simply paste a copy of the buttons above, save the file and see the changes on your browser immediately.

Notice how clicking on the button routes me to the /settings page, because I haven’t changed the routes.

Setting up a new page

Head to /v3/js/views/static.

This folder contains all the static pages.

Create a new page by copying any of the other static pages and renaming it.

Make sure to rename the component name and page contents as well.

/v3/src/js/views/static/AwesomePage.jsx

Routing

Head to /v3/src/js/routes.jsx .

Import our page to this file,

/v3/src/js/routes.jsx

Then route it to /awesomepage.

/v3/src/js/routes,jsx

Hit save and navigate to /awesomepage to see our new page!

Finally, let’s link our new button to the new page.

/v3/src/js/views/AppContainer.jsx

Now test our button and viola, it should work perfectly.

I hope that this guide has made it a little easier for you to get into open-source / NUSMods.

I will be writing more parts to the series where I’ll talk about GitHub and creating pull requests, the Redux paradigm and software testing, be sure to follow me to receive updates when the new parts are up!

Helpful Resources and Links


Zames is a software engineering intern at Hackwagon Academy, a Singapore-based programming school. He is also currently learning to contribute to NUSMods.