Contributing Code

Pre-Requisites

This is a project of the Hack for LA non-profit. To join this project as a developer, you must first complete the first four steps of Hack for LA Onboarding.

We can really only accept developers who have at least junior-level experience with React JS, as we do not have the resources to teach React to new developers.

Then review the "self test" in this slide deck: Developer Self Test. If you have performed all the tasks itemized on the first slide, then you should be qualified to join us as a Front-End developer. If you also have knowledge of the topics on the second slide (except CRON job scheduling), then you are qualified for a Full-Stack position on TDM.

Check the Available Position Board or contact us on the tdm-calculator Slack channel to see if we are currently in need of volunteers in the appropriate roles.

Contributing Code to the TDM Calculator Project - Getting Started

If you are not going to do hands-on development, you can simply experiment with the test version of the application at https://tdm-dev.azurewebsites.net.

The version that LA DOT personnel use for user acceptance testing is deployed to https://tdm-uat.azurewebsites.net.

The production site will be deployed to https://tdm.ladot.lacity.org

If you wish to study or contribute to the code base, follow the Installation Instructions below to install a development environment on your machine.

If you intend to make changes to the database structure or reference data, you will want connect to a local development database instead of the shared development database. See Local Database.

If you are involved in the release process and need to run an environment that exactly mirrors the deployment environments, you can develop and test in a docker development environment. See Deployment.

For a list of _other development topics, see Development.

Installation Instructions

Prerequisites

1. Git - for working with Github source code. On Windows, you will need to install Git for Windows as described on the Git-for-Windows-Installation wiki page.
2. Node and npm - we use Node LTS for running the web app (via lts-alpine on docker). We prefer installing Volta as a node/npm version manager. If you use volta then the TDM repo can use repo specific versioning instead of the machine default.

Full-Stack React/Node Application Installation

1. Start a terminal app, such as a Git bash shell on Windows or Terminal on Mac OS

2. Create a source directory (e.g. hackforla) in the user's home directory and go in it (or use the folder where you normally put local git repositories)

   mkdir hackforla
   cd hackforla

3. Clone the TDM repository

   git clone https://github.com/hackforla/tdm-calculator

4. Change to the tdm-calculator directory:

   cd tdm-calculator

5. Install the root level npm dev depedencies:

   npm install

6. Change to the server directory:

   cd ./server

7. Install the node server npm depedencies:

   npm install

8. Obtain the .env file from the tdm-calculator/Developers G-Drive folder and place it in this /server directory. It contains private info (i.e., the production database connection string) that we cannot put in this public GitHub repo.

9. Change to the client directory:

   cd ../client

10. Install the client (React) dependencies:

    npm install --legacy-peer-deps

To Run the React/Node Application

1. In one terminal window, navigate back to the /tdm-calculator root directory and start both node and react servers concurrently:

   cd ../
   npm start

This will first start up the node server; once the node server is up, then it will automatically start the frontend React server. You should see some processes running in your terminal, with either blue [BACKEND] or pink [FRONTEND] labels at the beginning of each line.

You may sometimes see messages that say port 5000 is already. You may have to wait a couple of seconds for the threads to finish processing. You will know it is working correctly when you see You can now view tdm-calculator-client in the browser and that http://localhost:3000 is running.

Alternatively, you can run the servers independently

If running the servers concurrently from the root directory does not work, you can run the servers independently.

1. In one terminal window, navigate back to the /tdm-calculator/server directory and start the node server:

   cd ../server
   npm start

2. In a separate terminal window, navigate to the /tdm-calculator/client directory, start the react app, and open the browser :

   cd client
   npm start

Note: Node server (backend) should start before the React server (frontend/client)

To Contribute Code

Claiming an Issue

Before modifying any code, an issue should exist for the task in the GitHub repo. You should make sure that no one else is assigned to the issue and then assign it to yourself, so we avoid stepping on each others' toes. If there is not an issue for the work you want to do, you should talk to the lead developer and/or project manager to get an issue created and prioritized on the kanban board and then have them create the issue from there for you to work on.

We use the "Git Flow" workflow to manage source code. See Vincent Driessen's seminal article for an overview, though a few of the detailed procedures below have additional steps. We have modified a few steps here, so your changes are merged into develop on GitHub (rather than locally). This allows others to easily view your changes, and is a smaller departure from the previous workflow to learn.

1. After cloning the repository, create a feature branch with a name containing your name and a feature name, separated by dashes, for example.

   git checkout -b 619-project-level-rule-change develop

   Note that your feature branch is based on the develop branch, which is where feature changes will be integrated for eventual release to production.

2. Claim an issue (see instructions down below) and start coding.

3. Regularly add, commit, and push your code to your branch.

   git add -A
   git commit -m "Write your commit message here with overall description of your code changes"

   Pay close attention to the messages you get when you try to commit. There is a git commit hook that will run eslint and prettier on your code to check for compliance with our coding conventions, and any deviation will be flagged as errors and block the commit from completing. You will need to resolve these problems and then try again.

NOTE: If you get an error bash: lerna: command not found on Windows 10 when you try to run the above commit command, you may need to add %AppData%\npm to your PATH Environment Variable and re-start your bash shell.

1. When an issue is completed and is ready for a pull request, first add and commit your latest changes as in Step 3 above, then make sure your code has the latest code from the develop branch by pulling from the develop branch. This is to ensure merge conflicts are in your local envinronment, which is easier to clean up, than in GitHub:

   git pull origin develop

2. Resolve any merge conflicts and run the application (client and server) to be sure that the application builds correctly before proceeding.

3. From the root directory, run:

   ./push.sh

   This will compare your code with the latest code from the origin/develop branch. Depending on if there are changes to the client, server, or both, this push script will run tests accordingly.

   If there are failing tests, please fix your code implementation to ensure test are passing, or if necessary, update the tests.

   Once tests are all passing, this script will automatically push your changes to a remote feature branch on the github repo.

   However, if you need to manually push your changes to a remote branch, you can run

   git push origin HEAD

4. Go to the GitHub repository for TDM-Calculator. There are three options:

   • Click on "Compare & pull request" button underneath the "commits branches releases environment contributors" box.
   • Click on the "New Pull Request" button underneath the "commits branches releases environment contributors" box and underneath "Your recently pushed branches" section.
   • Click on the "Pull Request" tab and press "New Pull Request"

5. In "Comparing Changes", switch the "compare" (right button) to your branch name. Make sure the "base" (left button) is on the develop branch. Double check the changes you've made down below, and click "Create pull request". Make sure the description of your changes is reflected in the Pull Request, e.g. "Start to incorporate Storybook and LADOT theme (colors, logos and headers)".

6. Click on "Create Pull Request" and wait for someone to review to merge your changes!

7. Once your PR has been reviewed, accepted and merged to the develop branch, it will automatically be published to https://tdm-dev.azurewebsites.net. Please be sure to run the application here and make sure your changes are reflected in this deployed version of the develop branch.