So, you've come here hoping to make Concourse better? Rad. There are lots of ways to do this, from just hanging around Slack to contributing to discussions in GitHub issues and, maybe at some point, contributing code.
This document will point you in the right direction for whichever ways you choose to contribute.
Growing the Community
Contributing to open-source projects can be done in more ways than just writing code. Often the most valuable thing for a project's growth is to have constant and healthy discussions.
There are a few ways you can help out here:
If you run into a bug or have a feature request, look for an issue for it, or create it if it doesn't already exist. If one already existed, you can either add GitHub reactions to it or make a comment providing additional info, but please don't leave comments that just say "+1" or "this is affecting me too and it's the end of the world".
GitHub reactions and comments are literally used to rank the issues and will get us to pay more attention to them.
Just about every large change we're thinking of making will start its life as a GitHub issue with the
discusslabel. These are meant to present a direction we're thinking of going and to collect feedback from the community on whether it'd help them.
The same rules apply for GitHub reactions and comments; they help us decide which things are affecting more people.
If you've got a feature you want to see or a bug you'd like to fix, pull requests are the way to go.
Finding things to work on
If you're a generous soul that just wants to give back to the community, but
don't know where to start, check out the
label! We'll typically apply this label to things that we think are valuable
but don't have the bandwidth to tackle ourselves. They'll usually be small
changes that a contributor could start with.
Submitting Pull Requests
There are only a few ground rules that we like to see respected for your pull-request to be considered:
Each change should have a corresponding test to go along with it. If you are having trouble testing, you can just submit the PR ahead of time and we'll be happy to help guide you along.
Pull requests should be focused. Please do not submit changes that mix multiple orthogonal changes together, even if you think they're all good.
All pull requests to the
concourse/concourserepo should be made to
develop, unless they're for documentation found via the repo itself, such as this one. Individual components however should be submitted to
Updating the documentation is encouraged but not necessary; we'll be sure to cover things before we ship the next version if you're not comfortable with writing the docs yourself.
With those ground rules out of the way, let's get you setup to work on the project!
Running Concourse locally
There are scripts under
dev/ to make running Concourse during development
easier for rapid iteration.
You'll just need the following:
- Go 1.7+
You can also pass arguments to start only certain components. This can be useful for starting everything but the bit you're working on, and then starting that one separately:
./dev/start db tsa worker # in shell A ./dev/atc # in shell B
Then you can just
./dev/atc process and restart it as you make
To start everything needed for a full Testflight run, run
The only difference is two additional workers: one with a tag, and another with
a proxiy configured. If your changes don't seem like they'd need those workers,
you can stick with
./dev/start - the tests will automatically skip themselves
if the workers are not present.
Making changes to Concourse
This repository acts as a Go development workspace, containing all the source
code for Concourse and its dependencies under
src/. You should first set
$PATH appropriately, which can be automated with
The other purpose of this repository is to build the BOSH
release, which is what
packages/, and most of the other directories
are for. If you're just contributing to Concourse and don't really care about
BOSH, you can just ignore those. It's purely a convenience for us to have it
all in one place.
Your workflow should consist of
cding to the component you want to change,
checking out the
master branch (they're submodules, so they default to
pointing to a detached
HEAD), and working from there, with your
to the root of this repository.
Then, once you're done with your changes, commit locally and push to a branch. From there you can submit a PR.
Don't worry about bumping the submodules; that tends to be too painful
to synchronize with multiple PRs in flight. We'll take it from there. If your
changes involve multiple components, though (
fly for example), be
sure to let us know in each PR.
There are multiple levels of testing in Concourse. If you're adding a feature or fixing a bug, you should also update the tests. If it's a fairly small change, it may be enough to just update the component-level tests. If it's larger though, it may be worth considering adding something to Testflight. This can also be a nice place to start as Testflight will definitely show whether or not your shiny new feature works, and a failing Testflight test is a nice thing to work towards making green.
Component-level unit/integration testing
The typical workflow here is: if you're making changes to a single component,
atc, just update the tests and then run:
This typically just runs
ginkgo -r -p after doing some additional checks and
If the component has a
CONTRIBUTING.md file of its own, be sure to read it -
there may be more to do.
Testflight runs against a real live
Concourse and runs
fly commands and configures pipelines and such. It takes a
little while (on the order of 10 minutes) but is a very good indicator of
whether things actually, like, work.
testflight should just be a matter of spinning up all the components
dev/ scripts, and running
ginkgo -r out of the
cd src/github.com/concourse/testflight/ ginkgo -r
You may want to speed things up by specifying
-nodes=N flag. Just don't use
-p as things will get a bit slow if there are too many parallel threads
contending for your machine's resources. Good values of
N are 2 or 3.