Welcome to CSESoc Projects and the Notangles team! This page will come in handy when you’re running Notangles locally, and working on your own features.

Your setup

Your coding setup is yours and we’ll try our best to support that, although here’s some recommendations. First off, using a Linux or Linux-like OS (such as macOS) makes everything a lot easier, although you can get by on Windows.

I encourage fellow Windows users to install WSL (Windows Subsystem for Linux), which essentially lets you run a virtual Linux box inside your Windows OS with minimal hassle. (Bonus: install Windows Terminal for enhanced aesthetics.) Some of this guide may be useful.

Once you’ve got your OS setup, there’s the question of editor. This is a personal choice, but if you’re looking for advice, you can’t go wrong with VS Code.

We use GitHub for managing our source code, which you can use mainly with commands in the terminal. But GitHub Desktop makes a lot of things easier if you’re not into that. However, you’ll probably need to learn the commands at some point in your career.

Our stack

Currently, Notangles is made up of a front-end (the client) and a back-end (the scraper and its server).

The client is what runs in a user’s web browser when they visit Notangles. It manages the UI and requests data from the server. It’s written in TypeScript, and uses a UI library called React, along with a component library called Material-UI and a styling library called Styled Components.

The server is currently unused as it was replaced by the new scraper, which has its own API. It used to fetch data from the database. We will bring it back online once we implement social timetabling and transition to using MongoDB with the scraper. The runtime is Node.js, which is an environment for executing JavaScript outside the browser, such as on a server. It uses a web server framework called Express.

The scraper is currently written in TypeScript and runs in Node.js. The code for the scraper can be found here. It uses a library called Puppeteer, which simulates a web browser to download and extract data from UNSW’s timetable website. Currently, the scraper writes the data to a file, but there are plans to migrate this to a MongoDB database which will also store user account data for our social timetabling feature. The scraper has its own API to provide access to this data.

These components are run on CSE machines in Docker containers. Docker makes running and deploying code much more portable, by simulating an OS and environment which behaves the same no matter what machine it’s running on. Learn more on our page about server containerisation.

Prerequisites

Before you start, make sure that you have the following software installed.

• Git (standard on Linux) or GitHub Desktop

• Node.js and npm (usually bundled with Node.js)

• Docker (only needed if you are working on the back-end)

  • Instructions if you’re using WSL on Windows

Getting the source code

We manage our source code with a version control system called Git. Every time we commit new code, it gets added to a history of commits, so we can get old code back if needed. This code is then hosted on GitHub, so any code you push is backed up, and can be pulled by other team members. Git has other features like branches, which allow us to work on different versions of the same codebase at the same time, and merge them together later.

First of all, make sure that you have been added to the Notangles repository on GitHub. While anyone can read our open-source codebase, you’ll need permissions to push changes.

Once you’re in, summon a terminal and clone the repository by running git clone git@github.com:csesoc/notangles.git (you can also use GitHub Desktop). After that, navigate into the newly-cloned repository by running cd notangles and then run cd client && npm i. This installs all the dependencies that the project needs. It should only need to be done once, unless the dependencies change.

Next, clone the scraper repository into the same folder as the Notangles repository by running git clone git@github.com:csesoc/timetable-scraper.git. Navigate to the repository by running cd timetable-scraper and then run npm i to install the scraper’s dependencies.

Running the back-end

(Skip this for now) Navigate into notangles/server and run docker-compose up. This runs the server and the database as a bundle.

(Start from here) After that, navigate to the timetable-scraper repo and run npm start to start the scraper’s server. To update the scraped data, run npm run scraper. This command should only need to be run once each term.

Running the front-end

Navigate into notangles/client, then run one of the follow commands:

• npm start (if you already have the scraper/server running locally; connects to that)

• npm run start:mock (if you don’t have the server running locally; connects to our real server)

You can then access the client at localhost:3000 in your favourite web browser.

Troubleshooting

If you have issues with any of the above, check out the troubleshooting page for some possible fixes. If that doesn’t help but you find a solution, please add your solution to the page.

Issue Boards

Notangles uses Jira to track tasks, issues and features.

The Jira is our main issue board. It keeps track of our epics and main tasks and any bugs which we have discovered. There is also a column for feature requests by the general public.

Workflow

When you’re working on a Jira issue, create a branch in Git with a name following one of these formats:

• feature/<issue-code>-<human-readable-name> (for adding a new feature)

• bugfix/<issue-code>-<human-readable-name> (for fixing a bug)

• hotfix/<issue-code>-<human-readable-name> (for urgent fixes, e.g. security patches)

The issue code is the 8-character code which appears in each Jira ticket e.g. NTGL-200

Then, push the branch to the Notangles repository by running git push -u origin <branch-name> (or by pushing on GitHub Desktop).

When you are finished with your work, create a pull request on GitHub, then assign as reviewers the team leads, and members with experience in the area.

When your pull request has been approved and merged into the dev branch, you can move the card into “Done” on Jira or archive the card on Trello. All archived Trello cards can be referenced from “archived items”, under “more” in the Trello menu.

As a side note, make sure to always pull from dev before you do any work! This is so you can get the latest code to work on, with all the new changes from other team members.

Style

To enforce a consistent style, install prettier as a VSCode extension and enable formatting on save in your text editor. This will read the .prettierrc in the repo and ensure that everyone is adhering to the style conventions we have laid out.