Build Tracker

Build Tracker

  • Docs
  • Guides
  • Demo
  • GitHub
  • Blog

›Guides

Getting Started

  • Getting Started
  • Performance Budgets

Configuration

  • Application
  • CLI

Plugins

  • Plugins
  • Postgres
  • MariaDB
  • MySQL

Guides

  • Guides
  • Continuous Integration
  • Writing documentation
  • Development
Edit

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

Development

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
Last updated on 9/7/2019 by Paul Armstrong
← Writing documentation
  • Getting started
    • Install dependencies
    • Make your changes
    • Open a pull request
  • Monorepo
    • Package workspace structure
  • Development
    • Adding a dependency to a package
    • Don't abstract too early
  • Typescript
  • Dev environment
  • Code integrity
Build Tracker
Docs
Getting StartedPlugins
Community
Stack Overflow
More
BlogGitHubStar
Copyright © 2019 Paul Armstrong