Contributing to Empire
A great way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate a well-written, thorough bug report, and will thank you for it! Check that our issue database doesn't already include that problem or suggestion before submitting an issue. If you find a match, add a quick "+1" or "I have this problem too." Doing this helps prioritize the most common problems and requests.
Please also include the steps required to reproduce the problem if possible and applicable. This information will help us review and fix your issue faster.
Submitting Pull Requests
We want the development of Empire to be driven by the needs of the community, so pull requests are highly encouraged. We do have some guidelines that we would like people to follow:
- If your change is non-trivial, or implements a new feature, please create an issue first so the community and maintainers can discuss the change before implementation happens.
When submitting a pull request, here are some things to keep in mind:
- Is your change backwards compatible? Would this require any migration steps? Will any changes be required in the CLI?
- Does your change require changes to the documentation? Does the quickstart guide need to be updated?
- Did you add appropriate test coverage? Submissions that add features or change core functionality will not be accepted without sufficient tests. We favor stability over anything else.
- Did you update the CHANGELOG?
Empire is a fairly large codebase, separated into packages that depend on each other. In a nutshell, the most important packages are:
- github.com/remind101/empire: This is the "core" internal API of Empire, which "control" layers (like the REST API) consume.
- github.com/remind101/empire/server: This contains an http.Handler implementation for serving the Empire API, which is what the
empCLI communicates with.
- github.com/remind101/empire/scheduler: This is the layer that the core of Empire interacts with for submitting releases to be scheduled on a cluster of machines. The canonical implementation uses CloudFormation + ECS to run applications.
- github.com/remind101/empire/cmd: Holds both the empire (daemon) command and emp (client) command.
The dependency graph for the packages above, and how they interact with each other looks like this:
Unit tests live alongside each go file as
There is also a
tests directory that contains integration and functional tests that tests the system using the [heroku-go][heroku-go] client and the [emp][emp] command.
The easiest way to run the tests is by using docker-compose.
To get started, run:
$ docker-compose -f docker-compose.test.yml build $ docker-compose -f docker-compose.test.yml up -d db
Then run the tests with:
$ docker-compose -f docker-compose.test.yml run tests
To get started, run:
$ make bootstrap
The bootstrap command assumes you have a running postgres server. It will create a database called
using the postgres client connection defaults.
To run the tests:
$ make test
NOTE: You may need to install libxmlsec1 for the tests to run. You can do this with:
$ brew install libxmlsec1 libxml2 pkg-config
If you want to contribute to Empire, you may end up wanting to run a local instance against an ECS cluster. Doing this is relatively easy:
Ensure that you have the AWS CLI installed and configured.
Ensure that you accepted the terms and conditions for the official ECS AMI:
Also check that the offical ECS AMI ID for US East matches with the one in cloudformation.json: https://github.com/remind101/empire/blob/master/docs/cloudformation.json#L20
Run docker-machine and export the environment variables so Empire can connect:
$ docker-machine start default $ eval "$(docker-machine env default)"
Run the bootstrap script, which will create a cloudformation stack, ecs cluster and populate a .env file:
Run Empire with docker-compose:
$ docker-compose up db # Only need to do this the first time, so that the db can initialize. $ docker-compose up
NOTE: You might need to run this twice the first time you start it up, to give the postgres container time to initialize.
Empire will be available at
http://$(docker-machine ip default):8080 and you can point the CLI there.
$ export EMPIRE_API_URL=http://$(docker-machine ip default):8080 $ emp deploy remind101/acme-inc
When you add a new dependency, be sure to vendor it with govendor:
$ govendor add <package>
Perform the following steps when releasing a new version:
- Create a new branch
- Bump the version number with
make bump(this will add a commit to the branch).
- Open a PR to review.
- Once merged into master, wait for the Conveyor build to complete.
- Finally, tag the commit with the version as
v<VERSION>. This will trigger CircleCI to:
- Tag the image in Docker Hub with the version.
- Build Linux and OS X versions of the CLI and Daemon.
- Create a new GitHub Release and upload the artifacts.
- Update the new GitHub Release to be human readable.
- Open a PR against Homebrew to update the emp CLI: https://github.com/Homebrew/homebrew-core/blob/master/Formula/emp.rb