Working on GWELLS

How to Contribute Code to GWELLS - Start to Finish

1. Get a ticket from Trello
2. Create a new git branch
3. Write code
4. Make a pull request
5. Merge
6. Release pipeline (Deploy new code to staging)
7. Deploy to production
8. Something went wrong!

Get a ticket from Trello

GWELLS issues are documented on our Trello board. If you already have access to the board and you want to notify others that you are taking on a ticket, click on the ticket and add yourself using the "Members" option.

If there is no Trello card/ticket yet for a bug in GWELLS, please make a new card or ask a team member to create one. This will give you a ticket to reference.

Create a new git branch

When you start working on a new feature or bugfix, always create a new branch for your work. If you don't have collaborator access to the bcgov/gwells repository, fork it to your own account. Only branches off the main repo will be automatically tested by continuous integration, so avoid using a fork if you already have collaborator access.

If you need help getting started, the README.md file in the GWELLS repo has more information.

Write code

After creating a new branch, start writing your code. You can use docker-compose up to bring up a full development server with all the necessary services for testing and trying out your code. See the README.md file for more information on local development. Make sure you run the tests.

Note: Please ensure changes to the database schema (migrations) are compatible with the existing codebase (add columns, but do not delete, rename, change type etc. in one step). This ensures a smooth rollout with no downtime and prevents bad things from happening if the app deployment needs to be reverted but the migrations cannot be.

Make a pull request

Once you have built a new feature or fixed a bug, push your changes up to GitHub and make a pull request against the release branch. The release branch holds new code that is on its way to production.

All pull requests need to be reviewed by somebody else on the team. This is a crucial step for getting feedback on your proposed solution, catching mistakes in the code, and making sure other team members understand how new parts of the code base work. Double check your own code before requesting review. Pull request reviews should always be a positive experience (no blame, condescension etc.).

Checks/tests

Pull requests made from a branch on the main repo (i.e., not a fork) will trigger some automated tests/checks, which will be displayed at the bottom of the pull request page. Here are the important ones:

• Build: this step runs JavaScript unit tests and starts building artifacts and docker images. If your build fails here, check the JavaScript tests.
• Deploy: this step deploys your pull request to a preview environment. A link will be added to the PR page. If this step fails, check the following:
  • Have you changed the Django models without committing a new migration?
  • Have you added any dependencies but forgot to update requirements.txt/package.json?
  • If the deployment is just taking extra time and you hit a timeout, you can retry in Jenkins. Ask a team member for an introduction to the OpenShift console and Jenkins.
• Django Unit Tests: this step runs the Django unit tests. If this step fails:
  • Ensure the python unit tests are passing on your machine.
  • Sometimes Jenkins fails to find the Django app container to start running the tests. If you get a "cannot find container" error, just retry the stage.
• API tests: This step runs Postman tests. If this step fails, ensure the Postman tests pass locally. Failing tests can be seen with the "Details" link.

Keycloak login for dev environments

Keycloak is not set up to automatically allow logging in from the automatically generated dev environments. To enable log in:

• Go to https://sso-test.pathfinder.gov.bc.ca/auth/admin/gwells/console/
• Select Clients from the left sidebar
• Select the gwells-test client
• Add the new URL (e.g. https://gwells-dev-pr-999.pathfinder.gov.bc.ca/gwells/*) to the list of allowed hosts.

Merge

Once approved, merge the pull request into release and delete your branch. Merging your PR will clean up your dev preview environment.

Release pipeline

Merging a PR into release will trigger the release pipeline. In about 15 minutes, your new feature will be deployed to the staging site. You can check the progress in the Release pull request, which is usually open.

No Release pull request? Open a pull request from release to master and the release pipeline will start automatically.

Deploying to production

Once the staging site has been updated with your freshly merged pull request and all the tests have passed, you can deploy to production in Jenkins. Click any of the "Details" links in the pull request stage checks/statuses on the Release PR page. Approving deployment to production will trigger a pre-deploy database backup, and then migrations will run, and then a "rolling" release will occur (the old application will stay up serving traffic until the new application is fully deployed).

Something went wrong!

Prod deployment

If there's an error in the production deployment, the application pod should revert to the previously running version automatically. However, if the database migrations were successful, they may still be applied. As long as migrations are always compatible with the previous version of code, that may not be an emergency. The database backup is available if really needed. See Restoring from a database backup in the Wiki.

Staging deployment

Errors in staging deployment can happen because your new application code and database migrations may be running for the first time alongside other recently-merged code and migrations. Check for migration conflicts (see OpenShift deployment logs in the TEST project, or just pull down the newest release code and try running it).

Dev deployment

If you think something went wrong with your dev deployment, you can create a brand new one simply by closing your PR and re-opening it.

Pipeline isn't running

• Check that there is an open Release pull request. If it's not there, open it and the pipeline will be triggered automatically.
• Check Jenkins has free executors available (see status of pipelines in bottom left). If all the executors are running, increase executors to 20 in manage jenkins or stop pipelines that are stuck/not needed.
• Check Quota in OpenShift (DEV environment). If environments/resources are not being cleaned up, this may prevent deployments from running ("Deploy to Dev" stage always failing). Check Manage Jenkins > In process script approval and make sure that the cleanup script is approved to run.