Skip to content

Latest commit

 

History

History
303 lines (203 loc) · 14 KB

Contributing.md

File metadata and controls

303 lines (203 loc) · 14 KB

Contributing to the TDM Calculator Project

If you are not going to do hands-on development, you can simply experiment with the test version of the application at https://tdm-calc-staging.herokuapp.com.

The version that LA DOT personnel are using is deployed to https://tdm-calc.herokuapp.com.

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

Installation Instructions

Prerequisites

  1. Git for working with Github source code
  2. Node and npm for running the web app

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 node server npm depedencies:

    npm install

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

  7. Change to the client directory:

    cd client

  8. Install the client (React) dependencies:

    npm install

To Run the React/Node Application

  1. In one terminal window, navigate back to the /tdm-calculator directory and start the node server:
cd ..
npm start
  1. 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 nicholas-issue-100 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.

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

  2. 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"
git push origin HEAD
  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
  1. Resolve any merge conflicts and run the application (client and server) to be sure that the application builds correctly before proceeding. Then push your changes to your feature branch on the github repo:
git push origin HEAD
  1. 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"

  1. 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)".

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

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

Creating a Release

Creating a release should only be done by the release manager! Release branches are created from the develop branch. Decide on a release number for the next release, using semver conventions. For example, if the current release is 1.0.0 and the changes in this release are minor, the new release number would be 1.0.1.

  • Make sure your local machine has an up-to-date version of the develop branch:
git checkout develop
git pull origin develop
  • Create a new release branch from develop with the name release-<release#>:
git checkout -b release-1.0.1 develop

  • Update the release number in the application. This typically entails updating the package.json file version properties, and perhaps other locations where the release number might appear (For now, I just added it to the About.js component, though we should probably put it in a site footer or some inconspicuous place, so it can be viewed from the UI.)

  • Commit the version number change:

git add -A
git commit -m "Bumped version number to 1.0.1"
  • Run the application (locally and/or in a deployment environment) and make any fixes necessary. These should be very minor changes - significant changes should be made by creating a feature release based on the develop branch as described above. When the application is ready for release...
  • Merge the release branch into master:
git checkout master
git pull origin master
git merge --no-ff release-1.0.0
git tag -a 1.0.1 -m "Release version 1.0.1"
git push origin HEAD
git push origin 1.0.1

At present, Heroku is configured to detect the commit to master and automatically deploy the application to production. You should navigate to https://tdm-calc.herokuapp.com after giving Heroku time to deploy and verify that the application runs, and any visible release # has been incremented.

The release is now done and tagged for future reference.

  • Merge the release branch into develop:
git checkout develop
git merge --no-ff release-1.0.1

(Resolve any merge conflicts)

git push origin HEAD

It will automatically be published to https://tdm-calc-staging.herokuapp.com. Please be sure to run the application here and make sure your changes are reflected in this deployed version of the develop branch.

  • We are now done with this release and can delete the release branch:
git branch -d release-1.0.1

Generating release notes

We are using gren with .grenrc.json config file and generating the log from Github Issues. See this page on the recommended convention for writing issue titles. We use the enhancement and bug labels to categorize issues for release notes.

  1. Follow instructions on the gren setup section to generate and install your Github token.

  2. Be in the project root directory

  3. Run the script to update the notes

npm run release-notes

Creating a HotFix

Creating a HotFix should only be done by the release manager! A HotFix should only include very minor patches to the application, and is always based on the master branch. The new release number will be the same as the master branch number with the patch number incremented by one. For example a patch to release 34.67.22 should be 34.67.23.

  • Make sure your local machine has an up-to-date version of the master branch:
git checkout master
git pull origin master
  • Create a new release branch from master with the name hotfix-<release#>:
git checkout -b hotfix-34.67.23 master

  • Update the release number in the application. This typically entails updating the package.json file version properties, and perhaps other locations where the release number might appear (For now, I just added it to the About.js component, though we should probably put it in a site footer or some inconspicuous place, so it can be viewed from the UI.)

  • Commit the version number change:

git add -A
git commit -m "Bumped version number to 34.67.23"
  • Run the application (locally and/or in a deployment environment) and modify the code to implement the fixe(s). These should be very minor changes - significant changes should be made by creating a feature release based on the develop branch as described above. When the hotfix is ready for release...
  • Merge the hotfix branch into master:
git checkout master
git pull origin master
git merge --no-ff hotfix-34.67.23
git tag -a 34.67.23 -m "Release version 34.67.23"
git push origin HEAD

At present, Heroku is configured to detect the commit to master and automatically deploy the application to production. You should navigate to https://tdm-calc.herokuapp.com after giving Heroku time to deploy and verify that the application runs, and any visible release # has been incremented.

The hotfix is now done and tagged for future reference.

  • Merge the hotfix branch into develop:
git checkout develop
git merge --no-ff hotfix-34.67.23

(Resolve any merge conflicts)

git push origin HEAD

It will automatically be published to https://tdm-calc-staging.herokuapp.com. Please be sure to run the application here and make sure your changes are reflected in this deployed version of the develop branch.

  • We are now done with this release and can delete the release branch:
git branch -d hotfix-34.67.23

Resources from our very own Hack For LA member!

Testing

We have three levels of testing built into the application at this time for just a few components/modules. Ideally, every React component should have a Storybook story and snapshot test, and critical non-react components should have good unit test coverage,as described below.

Storybook

Storybook creates a "visual style guide" of components. Ideally, every visual React component will have a storybook story that allows us to view what each component looks like without having to track down some sort of screen where it might be used. See this tutorial to get started with storybook. You can run the storybook preview page by running

npm run storybook

from the command line in the /client directory to view the storybook catalog for our project. Though this gives a human-visible look at a component, it does not really comprise an automated test of the component, so...

Unit Tests

Jest is used for unit testing of non-react ES6 modules, such as the tdm-engine. These also get run when you type

npm test

at the command line, and all should pass. In fact, we should eventually implement a "gated check-in" policy in github that automatically runs the unit tests, and blocks the check-in if any unit test fails. See the Create React App documentation on testing with Jest here for further information on how this works.

Cypress Integration Tests (aka Acceptance Tests aka End-to-End Tests aka Journey Tests)

Cypress is a front end testing tool built for the modern web. Cypress can test anything that runs in a browser. Cypress enables you to write all types of tests End-to-end tests, Integration tests, Unit tests. We're currently using Cypress for integration tests.

To run the Cypress Tests from the root directory, you will need 3 terminal windows open for the server, client, and cypress servers:

  • npm start or yarn start to start the backend node server
  • cd client to change into the client directory from the root directory
  • npm start or yarn start and start the frontend React server
  • cd cypress to change into the cypress from the root directory
  • npm run cypress or yarn cypress to start the Cypress Tests

After a moment, the Cypress Test Runner will launch.

  • Click Run all specs to run the tests.

You can read the Cypress Test Runner docs to learn more about the tool and how to debug using the test runner.