All are welcome to contribute. Please fork the repository and make pull requests against the main branch.
I love guiding new developers. For some, this is their first foray into coding. If you are brand new, please read the following section. Otherwise, skip ahead.
In order to start contributing, you will need to understand the following
- Understand what a Command Line Interface (CLI) is
- Familiarize yourself with a CLI text editor (Vim, Nano), or use an IDE. I recommend VSCode
- Create a GitHub account
- What is Version Control
- SSH keys to access GitHub from your CLI
- Git Commands
From https://www.hostinger.com/tutorials/what-is-cli
To put it simply, CLI stands for command line interface. It is a program that allows users to type text commands instructing the computer to do specific tasks.
GitHub hosts code online and allows developers to collaborate and version control their work. Create an account here https://github.com/join
Read about Version Control here https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control
See https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh
See https://www.freecodecamp.org/news/10-important-git-commands-that-every-developer-should-know/
The absolute basic you would need are
clonepullcheckoutstatusaddcommitpush
The first thing you want to do is to fork the repository. This copies the entire repository into your account. For this project, the associated license allows anyone to use the code however they like.
You would need to clone the repository to download it to your computer. After you have setup SSH keys for your GitHub account, on your Command Line Interface (CLI), enter git clone [email protected]:njyjn/sg-vaccine-tracker.git in the directory you would like to save the code.
Then, enter cd <NAME_OF_REPOSITORY> and run git status
The recommendation is to develop in the dev branch, then merge it into staging, then merge it into main. In software projects, the code running in production (consumer facing) is typically found in main or master. For this project, it is main. Checking out a branch allows you to switch to that branch (or version) and update the code in your local machine accordingly.
Read more about branching strategies here https://nvie.com/posts/a-successful-git-branching-model/
Enter git checkout dev to switch into the dev branch.
Once you are done writing code, you have to stage your changes. It helps organize bits of code you want into commits.
To visualize, think about this Recycling metaphor. You only have one bin at your place. You would place your bottles into "Glass", paper into "Paper" and food into "Compostable"; but since you only have one bin, you can only sort your waste one type at a time. Staging is the same as placing your code into the Recycling Bin based on the 'category', or in development terms, the reason why the code is being added or modified.
To stage, enter git add -p. The CLI will then guide you through which changes you want to include and which ones you want to save for later.
Back to the Recycling metaphor. When you are done sorting your code, you want to send it to the Recycling Company. They expect you to tell them what the bin contains. So, you have to leave a message, for example,
git commit -m "Add glass bottles for recycling"
Typically, the message you write follows this pattern
<verb> <noun> <reason>
In this repo, all you need to pay attention to is the verb e.g. Add, Change, Fix, Allow and the reason.
After you are done committing your changes, go back and stage more code if you have.
Think of the push as the Recycling Company hauling away all your bins that you have given them. Similarly, all new commits you have made will go out in the same push and online to GitHub. Once you are ready to upload your changes, enter
git push
You may encounter an error in the CLI, especially if its your first time. If so, simply copy the command suggested and hit enter.
Congratulations! You have pushed your first commits to the repository. For now, we will stick to the dev branch.
Read the next section to find out how to work with code in this repository
The repo is split into two directories, api and client. Information about the two can be found in the respective README.md. Code in the api takes care of the backend data scraping, storage and API interfacing, while code in the client takes care of the frontend visual presentation. They are meant to be completely independent from each other.
The api is served by AWS Serverless, while the client is a React app running in a dyno in Heroku.
Please leave deployments to the code owner.
This project is able to be run locally. Install the package dependencies in the respective directories api and client using npm npm i.
The AWS CLI is needed to sign certain requests, even though no actual connection to AWS is being made. Install AWS CLI here and go through the setup to configure with some actual credentials.
Request credentials from the CODEOWNER or use your own. Setup your credentials as such
$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]:
Default output format [None]: jsonDocker is needed to host a local copy of the Database and, optionally, the backend and frontend. Install Docker here.
Within the api root directory:
If you haven't done so, clone the .env.sample file and rename it to .env.local. These variables are needed so that the SSM plugin can mock them for offline use.
Run the following
./scripts/run_offline.sh
You are now ready to make requests using the front end
Rename .env.sample to .env.
The client is easier to set up. Enter npm run start
A successful offline run results in a http://localhost:8081 page getting data from the backend API and displaying the counts. Otherwise, in case of error, an error page is shown.
Assuming you have met the prerequisites for the API and Client services above, you can run both of them using Docker without having to download anything else.
docker-compose upAccess the client on your browser using http://localhost:8081/
When done, run docker-compose down.
Unit tests are only currently available for the API. Add unit tests to the __tests__ directory and run using npm test.
Place any mock fixtures into __mock__.
Please make all pull requests to njyjn/sg-vaccine-tracker against the dev branch.