Developer Guide - Enterprise-CMCS/macpro-mako GitHub Wiki

Pre-Commit Usage

How to use pre-commit on the project

Context

Pre-commit is a python package that enables projects to specifies a list of hooks to run before a commit is made (a pre-commit hook). This is really useful to enforce standards or conventions, as it prevents non conformant changes from getting committed.

On this project, we use pre-commit to automate several checks, including:

running a code formatting check based on prettier
checking for large files typically not desired to keep in source control
scanning for secret material, such as AWS keys

Aside from these checks being run prior to any commit being pushed, they are also run by a GitHub Actions workflow when a pull request is made.

Installation

Good news! If you completed onboarding and ran the workspace setup script, pre-commit should already be installed on your machine.

You can test that it's installed by running pre-commit -V in a terminal window. If you get a nominal return including a version number, you're all set. If the pre-commit command is not found, please refer back to the Onboarding / Workspace Setup section of this site. If pre-commit is not installed it is important to get it installed and setup on your machine. This is a part of the workflow for developing apps in this architecture. Luckily setup is simple.

Configuration

Although pre-commit is installed on your workstation, you must configure pre-commit to run for a given repository before it will begin blocking bad commits.

This procedure needs to only be run once per repository, or once each time the .pre-commit-config.yaml file is changed in the repository (very infrequently).

open a terminal
install all hooks configured in .pre-commit-config.yaml
```
  cd macpro-mako
  pre-commit install -a
```

That's it -- after running the above commands inside the project repository, pre-comit will run the project's configured checks before any commit.

Update from Base

How to update your project with the latest macpro-base-template releases.

Summary

This command fetches the latest macpro-base-template changes and merges them into your branch. You may then resolve any merge conflicts, and open a PR.

Prerequisites:

Completed all onboarding

Procedure

Use the run script:
```
  nvm use
  run base-update
```

List Running Stages

How to get a list of currently running stages for this project in the current AWS account.

Summary

This returns a list of currently running stages for this project in the current AWS account.

Prerequisites:

Completed all onboarding

Procedure

Obtain and set AWS CLI credentials
Use the run script:
```
  nvm use
  run listRunningStages
```

Run Report using GitHub Actions

Summary

This project uses GitHub Actions as its CI/CD tool.

Each of our repositories has a GitHub Actions workflow added to run this list running stages command and report the results to slack on a schedule. This workflow may also be manually invoked.

Prerequisites:

Git repo access; complete the Git access request portion of onboarding
Access to CMS slack to see the generated report.

Procedure

Browse to the actions page of the repository in GitHub, select the "Running Stage Notifier" workflow and press run workflow.

Running Top Level Commands

Overview

The src/run.ts file defines many helpful commands you can use to perform helpful tasks for your project. This file utilizes Yargs to provide command line interfaces to several commands for managing a serverless project.

This code at src/run.ts is implementing a command-line interface (CLI) for your project. The CLI accepts various commands to manage and deploy the project. The CLI tool uses the yargs library to parse the command-line arguments.

The CLI provides the following commands to use like run [command] [options]

Commands

install installs all service dependencies. ui configures and starts a local React UI against a remote backend. deploy deploys the project. test runs all available tests. test-gui opens the unit-testing GUI for vitest. destroy destroys a stage in AWS. connect prints a connection string that can be run to 'ssh' directly onto the ECS Fargate task. deleteTopics deletes topics from Bigmac which were created by development/ephemeral branches. syncSecurityHubFindings syncs Security Hub findings to GitHub Issues. docs starts the Jekyll documentation site in a Docker container, available on http://localhost:4000.

Options

Each command has its own set of options that can be passed in the command line.

For example, if the command deploy is used, it requires the options stage (type string, demanded option), and service (type string, not demanded option). The behavior of the command is defined by an async function, which will run the installation of all service dependencies and will execute the deployment process through the runner.run_command_and_output function with the command SLS Deploy and the options set in the command line.

The same approach is used for all other commands. They all start by installing the dependencies of the services, and then perform specific tasks based on the options passed in the command line.

The docs command starts a Jekyll documentation site in a Docker container. If the stop option is passed as true, it will stop any existing container. Otherwise, it will start a new container and run the documentation site at http://localhost:4000.

Unit Testing

Overview

Unit testing is done using the vitest framework.

Vitest

Vitest is a unit testing framework for testing JavaScript code. It allows you to write tests in a simple and concise manner, and provides tools for running and reporting on the results of those tests.

Running Tests

Tests can be run using the top level run commands:

run test --stage [stage] - running all tests
run test-gui --stage [stage] - running all tests displaying results in browser ui