CONTRIBUTING.md

Orchestration 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 Orchestration repo uses scripts the deploy TERArium on various environments.

To deploy the application locally:

1. Stand up the servers by running the deploy-terarium.sh up script from within the kubernetes/local directory.
2. Navigate your browser to localhost:8078/app

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.

2. Save your personal access token (classic). We recommend saving your username and token as an environment variable.

   export USERNAME=[your GitHub username]
   export CR_PAT=[GitHub Personal Access Token]

3. 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

Kubernetes

To have Kubernetes access a private container image or repository it needs to have a generated secret available to do so. For use with the GitHub Container Registry you will again need a Personal Access Token(PAT), or reuse the same one as before.

Create Secret

To create the secret for kubernetes use the following command:

kubectl create secret docker-registry ghcr-cred --docker-server=ghcr.io --docker-password=$CR_PAT --docker-username=$USERNAME

where those values have been defined in the previous step:

• $USERNAME is your GitHub username.
• $CR_PAT is your GitHub PAT.

You have successfully set your credentials in the cluster as a Secret called ghcr-cred.

Verify Secret

To verify that the secret was generated use:

kubectl get secret ghcr-cred --output=yaml

Use Secret In Pod

To apply the secret to a pod simply reference it within the spec using the imagePullSecrets property.

Here is an example POD that accesses the secret credentials generated above.

apiVersion: v1
kind: Pod
metadata:
  name: private-reg
spec:
  containers:
  - name: private-reg-container
    image: <your-private-image>
  imagePullSecrets:
  - name: ghcr-cred

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.

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

• PR title should follow the commit message convention so that changelogs can be automatically generated.

• 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).

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