Development

Thank you for your interest in helping out with Build Tracker! This is a project done with joy and care, out of our free time. Before getting started, please familiarize yourself with the Contributor Covenant Code of Conduct.

Getting started

Fork and pull the repository from Github. If you're unsure how to fork a repository, read the getting started docs here.

git clone [email protected]:<myuser>/build-tracker.git

Once you've pulled the repository, you'll be working on the next branch. This may be slightly different from what you're used to, so make sure to pay attention to always keep the next branch up to date, and don't worry about master.

Install dependencies

Build Tracker is a monorepo managed by Yarn. Start by installing dependencies for all packages:

cd build-tracker
yarn

Make your changes

Always work on features in a separate branch from the main next or master branch.

git checkout -b my-feature

Now that you're on a branch, make changes directly to the code related to your feature or bug fix.

Ensure to always add tests, preferrably before you start making changes. This helps both you and any future reviewer verify that the code's intentions work correctly.

Run tests using the main script from the root of the repository:

yarn test

Once you've completed your changes and all of your tests pass, commit and push your branch to your fork:

git commit -am "[bugfix] a short description of what I did"
git push

Open a pull request

Finally, open a pull request on the main Build Tracker repository.

Monorepo

The Build Tracker git repository is a monorepo that is composed of many publishable packages. This has been done so that it's easier to iterate on cross-functional dependencies without requiring premature publishing steps.

The tool for managing these packages is Lerna with Yarn workspaces.

Package workspace structure

├── docs
│   └── website
├── plugins
│   ├── with-mariadb
│   └── with-postgres
└── src
    ├── api-errors
    ├── app
    ├── build
    ├── cli
    ├── comparator
    ├── fixtures
    ├── formatting
    ├── server
    └── types

Source `./src`

All core Build Tracker packages reside here.

All folder names should be mapped as the publishable name without the @build-tracker scope. For example: @build-tracker/app is in the path src/app, while @build-tracker/server is at src/server.

Plugins `./plugins`

All implementation-specific code for various integrations should be kept here, instead of in the src directory.

All folder names should be mapped as the publishable name without the @build-tracker/plugin- scope. For example: @build-tracker/plugin-with-mariadb is in the path plugins/with-mariadb.

Some local configs are available for development purposes. To use them, it's recommended to use a Docker container, since it's easy to seed and throw away:

MariaDB

docker run -p 3307:3306 --name bt-mariadb -e MYSQL_ROOT_PASSWORD=tacos -e MYSQL_ROOT_HOST=% -e MYSQL_DATABASE=buildtracker -d mariadb --default-authentication-plugin=mysql_native_password
yarn ts-node src/server/src/index.ts setup -c ./config/mariadb.js
yarn ts-node src/server/src/index.ts seed -c ./config/mariadb.js
yarn dev:mariadb

MySQL

docker run -p 3306:3306 --name bt-mysql -e MYSQL_ROOT_PASSWORD=tacos -e MYSQL_ROOT_HOST=% -e MYSQL_DATABASE=buildtracker -d mysql --default-authentication-plugin=mysql_native_password
yarn ts-node src/server/src/index.ts setup -c ./config/mysql.js
yarn ts-node src/server/src/index.ts seed -c ./config/mysql.js
yarn dev:mysql

Postgres

docker run --name pg -e POSTGRES_PASSWORD=mysecretpassword -e POSTGRES_DB=buildtracker -p 54320:5432 -d postgres
yarn ts-node src/server/src/index.ts setup -c ./config/postgres.js
yarn ts-node src/server/src/index.ts seed -c ./config/postgres.js
yarn dev:postgres

Docs `./docs`

This directory holds packages related to the documentation website

Here are some things to keep in mind while working in a monorepo:

Adding a dependency to a package

To add a third-party dependency to a sub-package in the Build Tracker repository, ensure that it's done from the specific sub-package using the yarn workspace command:

# To add to the @build-tracker/app package
$ yarn workspace @build-tracker/app add <some-third-party-module>

Don't abstract too early

Repeating code is not inherently bad. If some logic clearly fits in one of the already published packages, that's probably the right place for it. If there isn't a package available for something that is reusable, use your best judgement about complexity and scope of functions to determine if a new package is warranted.

Typescript

Build Tracker is written in Typescript throughout all workspaces. Please do not add code that is not written in Typescript or change to another language.

Dev environment

To run the development environment, some shortcuts are provided in the package.json scripts:

yarn dev Run the server and application in a hot-reloadable environment using pre-seeded builds on the filesystem
yarn dev:maria (coming soon) Run the server using a local MariaDB instance
yarn dev:postgres (coming soon) Run the server using a local Postgres instance

Code integrity

The following conformance checks can be run manually and will be automatically run on pre-commit as well as during the pull-request verification flow via Github Actions.

yarn lint Lint and auto-format code
yarn test Jest tests
yarn tsc Typescript type check