Developing Athena Partitions

Development Setup

This document describes how to set up your development environment to build and test Athena Partitions, and explains the basic mechanics of using git, go, yarn, terraform etc…

Installing Dependencies

Before you can build Athena Partitions, you must install and configure the following dependencies on your machine:

Set up

Simply run the following make command to configure you local dev environment:

make install

Running Tests

Running the Unit Test Suite

We write unit and integration tests.

make test

Running the End-to-end Test Suite

Athena Partitions unfortunately doesn’t have a true end-to-end test suite, since we haven’t developed a test environment to support it. Instead we can run all the build and test commands we have available. Simply run:

make all

This will build, test, lint and run static code analysis.

Coding Rules

To ensure consistency throughout the source code, keep these rules in mind as you are working:

Git Commit Guidelines

We follow v1.0.0 of the Conventional Commits specification for commit message formatting. This leads to more readable messages that are easy to follow when looking through the project history.

We also use the git commit messages to generate the Athena Partitions change log.

The commit message formatting can be added using a typical git workflow or through the use of a CLI wizard (Commitizen). Alternatively you can simply run the make install command to install husky with the commitizen cli pre-commit hook.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and the scope of the header is optional.

Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Revert

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Type

Must be one of the following:

Scope

The scope could be anything specifying place of the commit change.

Subject

The subject contains succinct description of the change:

Body

Just as in the subject, use the imperative, present tense: “change” not “changed” nor “changes”. The body should include the motivation for the change and contrast this with previous behavior.

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit closes.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

A detailed explanation can be found in this document.

Writing Documentation

Building and viewing the README locally

The docs can be built from scratch using make:

make docs

General documentation with Markdown

Any text in tags can contain markdown syntax for formatting. Generally, you can use any markdown feature.

Headings

Only use h2 headings and lower, as the page title is set in h1. Also make sure you follow the heading hierarchy. This ensures correct table of contents are created.

Code blocks

In line code can be specified by enclosing the code in back-ticks (`). A block of multi-line code can be enclosed in triple back-ticks (```) but it is formatted better if it is enclosed in <pre>…</pre> tags and the code lines themselves are indented.