Custodian

Custodian is an opinionated GitHub bot to automate routine development tasks. It was built by NewAperio and is designed to follow our conventions.

Currently, Custodian performs the following functions:

• When a new pull request is opened, adds needs-review label
• When a pull request is closed, removes all labels and deletes branch
• When a pull request is reopened, removes all labels
• When a pull request review is approved, removes needs-review and in-progress labels and adds ready-to-merge; merges changes from base branch to keep head updated
• When a pull request review is changes requested, removes needs-review and ready-to-merge labels and adds in-progress

The labels Custodian applies are a part of the NewAperio spec.

Installation

Custodian can be installed from its GitHub app page. Click the "Install" button and select which repositories to run on. Custodian will then run on any new pull requests.

Development

Getting Started

Before you begin, make sure you have the following installed and configured:

• BEAM, the Erlang VM
• Elixir
• Hex
• Mix
• PostgreSQL

After you've cloned this repo, install the dependencies with Mix:

% mix deps.get

Next, initialize the database (make sure PostgreSQL is running):

% mix ecto.create
% mix ecto.migrate

To start the app, run the server command:

% mix phoenix.server

The server runs by default on localhost:4000.

Documentation

The codebase is documented where appropriate. The docs are available on GitHub in HTML form. To view the docs, click here.

To view the docs in development, run ExDoc:

% mix docs

This generates an HTML version available in the doc/ folder. Open to view:

% open docs/index.html

To publish changes to the docs hosted on GitHub Pages, run the update script from master:

% git checkout master
% ./bin/update-docs

Testing

This project uses Test-Driven Development. For any new feature, tests should be written to verify appropriate behavior. We prefer to avoid testing framework, project, or library behavior and instead focus on testing the business logic of the app.

Tests should be terse and focus on a single component, in order to avoid coupling features. This will ensure tests accurately describe a feature's behavior.

Pull requests should not be accepted without appropriate tests covering any new behavior. Those PRs that fix bugs should include tests verifying the fixed issue.

All tests can be found in the test directory. To run the entire test suite, use Mix:

% mix test

Code Style

This repo includes Credo, a linting tool for Elixir. You can run it via Mix:

% mix credo

This repo also includes Sobelow, a static analysis tool for security issues. You can run it via Mix:

% mix sobelow

This repo also includes full Elixir typespecs which can be verified by Dialyzer. You can run it via Mix:

% mix dialyzer

Github Labels

Every issue on GitHub should be labeled appropriately with its status, area of focus, and type of implementation. We follow a standardized list of labels.

Every PR on GitHub should be labeled appropriately with its status.

Here are the labels we use in this repo:

Contributing

Always create a feature branch for any new code. Use the following naming scheme: github-user-name-feature-name (so who owns the branch and what purpose it serves can quickly be determined). Start with a branch based on master.

% git checkout master
% git pull
% git checkout -b github-user-name-feature-name

Pull in new changes on master frequently to avoid major conflicts.

% git fetch origin
% git rebase origin/master

When the feature is complete, make sure the tests pass.

% mix test

It's also a good idea to run any code style checks.

Make a pull request when the feature is complete. Write a good commit message.

% git add -A
% git status
% git commit -v

Push to Github and create a pull request.

% git push origin github-user-name-feature-name

Open a PR with a descriptive name and full description. Explain the nature of the change, the motivation for the change, and the thinking behind the implementation. Add links to supporting material and/or reference related issues. Tag the PR with the needs-review label and await peer review.

After CI passes and you get an approved PR review, merge the changes into master.

First, rebase. Pick only commits that are necessary. Squash others.

% git fetch origin
% git rebase -i origin/master

View the changelog, merge and push.

% git log origin/master..github-user-name-feature-name
% git diff --stat origin/master
% git checkout master
% git merge github-user-name-feature-name --ff-only
% git push

Clean up remote and local branches.

% git push origin --delete github-user-name-feature-name
% git branch -d github-user-name-feature-name

Deploying

Custodian is hosted on Heroku. Currently only a productio instance is available. Deploying is a simple git push:

% git push production

External Services

• Performance metrics and error tracking via AppSignal

Architecture Notes

• Runs on Erlang 20.2
• Runs on Elixir 1.5.3
• Runs on Phoenix 1.3
• Uses PostgreSQL as a relational data store
• Uses ExUnit for testing
• Deployed to Heroku

License

Custodian is copyright (c) 2017 NewAperio, LLC. It is licensed under the terms in the LICENSE file.

About NewAperio

Custodian is built by NewAperio, LLC.

NewAperio is a web and mobile design and development studio with offices in Baton Rouge, LA and Denver, CO.