Skip to content

Latest commit

 

History

History
264 lines (183 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

264 lines (183 loc) · 10.5 KB

Terarium Contributing Guide

Hi! We're really excited that you're interested in contributing to Terarium! Before submitting your contribution, please read through the following guide.

Repository Setup

The Terarium repo is a mixed repo using yarn workspaces and Java backend components. The package managers used to install and link dependencies are yarn and gradle.

To develop and test the core application:

  1. Stand up the Terarium services by running the deploy-terarium.sh up script from within the Orchestration repository
  2. To stop a pod from running in kubernetes so that you can run locally to debug, run the following commands from the orchestration repo's kubernetes/local directory. Replace [NAME] with the name of the service you would like to stop (e.g. hmi-client or hmi-server).
  • kubectl delete -f [NAME]-deployment.yaml -f [NAME]-service.yaml
  1. Start a service locally to replace the services you shut down
  • Start up the Backend SpringBoot server using ./hmiServerDev.sh command from the root directory
  • Start the front end by doing yarn && yarn dev (shortcut for yarn install && yarn workspaces hmi-client dev)
  1. Navigate your browser to localhost:8078
  2. You can start services back up in kubernetes by running the following commands from the orchestration repo's kubernetes/local directory. Replace [NAME] with the name of the service you would like to stop (e.g. hmi-client or hmi-server).
  • kubectl apply -f [NAME]-deployment.yaml -f [NAME]-service.yaml

Container Registry Setup

This project uses GitHub Container Registry as its hub. In order to push and pull images generated by the repositories you need to login into the registry. By default packages are private to members of the organization so if you have access to the repository you will have access to the registry after login ing.

Login To Registry

  1. Create a new personal access token (classic) with the appropriate scopes for the tasks you want to accomplish. If your organization requires SSO, you must enable SSO for your new token.

    Note: By default, when you select the write:packages scope for your personal access token (classic) in the user interface, the repo scope will also be selected. The repo scope offers unnecessary and broad access. As a workaround, you can select just the write:packages scope for your personal access token (classic) in the user interface with this url: https://github.com/settings/tokens/new?scopes=write:packages.

  • Select the read:packages scope to download container images and read their metadata.
  • Select the write:packages scope to download and upload container images and read and write their metadata.
  • Select the delete:packages scope to delete container images.

For more information, see Creating a personal access token for the command line .

  1. Save your personal access token (classic). We recommend saving your token as an environment variable.
export CR_PAT=YOUR_TOKEN
  1. Using the CLI for your container type, sign in to the Container registry service at ghcr.io.
echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
Login Succeeded

Debugging Front End

To debug the front end you need:

  1. Add a debugger statement where you want to stop the code execution.

  2. Click the "Run and Debug" icon in the activity bar of the editor, which opens the Run and Debug view.

  3. Click the "JavaScript Debug Termimal" button in the Run and Debug view, which opens a terminal in VS Code.

Releasing

New docker images are automatically built when changes are pushed into main. This will generate all images with the latest tag associated with it. For releasing of new stable versions simply add a git tag on main of the form v#.#.# or v#.#.#-[a..z]. This will automatically trigger a retagging of the latest build with the specified tag.

NOTE: Careful that you wait until the main build has completed so that the tag is pulling the correct latest

Debugging in IntelliJ

Back End

Application Secrets

To add or modify application secrets (like passwords and API keys)...

Install Ansible

Required to encrypt/decrypt secrets.

brew install ansible
  • There is an ansible encrypted vault located in packages/server/src/main/resources/application-secrets.properties.encrypted
  • These instructions assume you have the vault password in your home directory in a file named askem-vault-id.txt
  • You can find this file in the ASKEM TERArium (Shared External) drive on Google Drive
  • There is a husky script which ensures that the secrets file is not committed unencrypted.
  • The outputed unencrypted file is gitignored to never be comitted.
  1. Decrypt the secrets vault via ansible-vault
./hmiServerDev decrypt
  1. Notice that in the resources directory there is now a application-secrets.properties file. Add the secrets that you want to this file.
  2. Re-encrypt the file to commit via the command
./hmiServerDev decrypt
  1. In the Orchestration project, add the secret to the correct file with the prefix of %prod
  2. When comitting you'll only be comitting the encrypted file, never anything unencrypted.

Running Tests

Integration Tests

Each package contains a tests directory which may contain one or both of e2e and ct subdirectories. The tests are run using Vitest + Playwright.

Before running the tests, make sure that Terarium has installed dependencies and has been built.

  • yarn test:e2e by default runs every integration across all 3 browsers (Chromium, FireFox, WebKit)
  • yarn test:ct runs component specific tests

Writing Integration Tests

Tests have access to the page object from Playwright (Page) instance that has already navigated to the served main page. So, writing a test is as simple as:

import {test, expect} from '@playwright/test';

test('should work', async (page) => {
  expect(await page.textContent('.foo')).toMatch('foo')
})

Unit Tests

Along with integration tests, packages also contain unit tests under their tests/unit directory. Unit tests are powered by Vitest. The detailed config is either inside vite.config.ts or vitest.config.ts files.

  • yarn test runs unit tests under each package.

Writing Unit Tests

Writing unit tests is simple and very similar to integration tests. Unit tests also have the same APIs as JEST so if you are familiar with that this should be simple:

import {assert, describe, expect, it} from 'vitest';

describe('basic tests', () => {
  it('should have the correct square root', () => {
    assert.equal(Math.sqrt(4), 2);
  });
});

Pull Request Guidelines

  • Checkout a branch from a base branch (main), and merge back against that branch.

  • If adding a new feature:

    • Add accompanying test case.
    • Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first, and have it approved before working on it.
    • Reference the feature ticket if applicable

  • If fixing a bug:

    • Reference the issue being resolved by adding (resolves #123)
    • Provide a detailed description of the bug in the PR. Live demo preferred.
    • Add appropriate test coverage if applicable.

  • It's OK to have multiple small commits as you work on the PR. GitHub will automatically squash them before merging.

  • Make sure tests pass!

  • Follow the PR template guide to submit your PR with the appropriate required information for review.

  • PR title must follow the commit message convention so that changelogs can be automatically generated. PR messages are automatically validated before being able to be merged by the use of GitHub Workflows.

  • No need to worry about code style as long as you have installed the dev dependencies. Modified files are automatically formatted with Prettier on commit (by invoking Git Hooks via Husky).

Ignore commits in the blame view

For all merged commit to main that needs to be hidden from the blame view, add the full hash to .git-blame-ignore-revs. To make sure your local git configuration is set up to ignore these commits, run the following command:

git config blame.ignoreRevsFile .git-blame-ignore-revs

For more information: git-blame-ignore-revs and on github

Maintenance Guidelines

The following section is mostly for maintainers who have commit access, but it's helpful to go through if you intend to make non-trivial contributions to the codebase.

Issue Triaging Workflow

flowchart TD
	A{Followed issue template} --> |Yes| C{Is duplicate?}
	A -->|No| E[Close and ask to follow template]
	C -->|No| F{Is actually a bug?}
	C -->|Yes| D[Close and point to duplicate]
	F -->|Yes| G[1. Remove 'triage' label\n2. Add 'bug' label\n3. Add 'priority' label]
	G -->K{Does bug make app unusable?}
	F -->|No| H{Is expected behaviour?}
	H -->|Yes| I[Explain and close]
	H -->|No| J[Keep open for discussion]
	K -->|Yes| L{Does it affect majority of users?}
	K -->|No| M{Is there a workaround?}
	L -->|Yes| N[Label as 'critical']
	L -->|No| O[Label as 'high']
	M -->|Yes| P[Label as 'medium']
	M -->|No| Q[Label as 'low']
Loading

Pull Request Review Workflow

flowchart TD
	A{Bug fix or feature?}
	A --> |Bug Fix| B{Strict fix without side effects?}
	A --> |Feature| C[1. Add `enhancement` label\n2. Discuss feature need\n3. Review code]
	C --> D
	B --> |Yes| D[1. Verify fix locally\n2. Review code\n3. Require tests\n4. Request changes if needed]
	D --> E[Approve or Reject]
	B --> |No| G[Discuss potential issues, are there too many changes?]
	G --> H[Add priority labels and additional relevant reviewers for discussion]
	H --> D
	E --> F[Merge if approved by 2 or more members\n 1. Use 'Squash and Merge'\n2. Edit commit message to follow convention\n3. Add relevant issues reference in body]
Loading