launchpad.net/~rogpeppe/juju-core/500-errgo-fix@v0.0.0-20140213181702-000000002356/CONTRIBUTING

Getting started
===============

Before contributing to `juju-core` please read the following sections describing
the tools and conventions of this project. This file is a companion to README
and it is assumed that file has been read prior.

cobzr
-----

juju-core uses bzr for source control. To make the bzr branching strategy more
palatable for the go toolset `juju-core` recommends using the `cobzr` helper.
`cobzr` allows the user to juggle multiple branches in place in a way that is
compatible with GOPATH. While it is possible to manage bzr branches manually,
the remainder of this document will assume cobzr is in use as practiced by the
juju-core team.

To install `cobzr`,

    go get launchpad.net/cobzr

TODO(dfc) document PPA version

It is recommended to use alias `cobzr` to `bzr`.

    alias bzr=cobzr

As `cobzr` passes any options it does not handle to `bzr`, it is safe, and recommended
to add this alias command to your login shell.

lbox
----

`juju-core` uses `lbox` for code review and submission. In addition `lbox` enables
the use of prerequisite branches.

To install lbox

    go get launchpad.net/lbox

TODO(dfc) document PPA version

Branching
=========

All changes to `juju-core` must be performed on a branch, that branch reviewed,
then submitted. An overview of the commands used to do so follows. These
examples use the `bzr` command, which is assumed to be aliased to `cobzr`, as
described above. It is also assumed that your working directory is
$GOPATH/src/launchpad.net/juju-core.

First, create a branch for your change using the following command

    bzr branch lp:juju-core/ add-CONTRIBUTING

This will branch `juju-core` and create a new branch called `add-CONTRIBUTING` in
your local workspace. Importantly this will not switch to this branch immediately,
so to switch to this branch use the following

    bzr switch add-CONTRIBUTING

At this point your previous branch will be stashed and the working copy updated
to match the state of the `add-CONTRIBUTING` branch. You must ensure any
outstanding changes to the previous branch are committed or reverted to avoid
local merge issues.

You can also list any branches you are currently working on by

    bzr branch


Imports
-------

Import statements are grouped into 3 sections: standard library, 3rd party
libraries, juju-core imports. The tool "go fmt" can be used to ensure each
group is alphabetically sorted. eg:

    import (
        "fmt"
        "time"

        "labix.org/v2/mgo"
        gc "launchpad.net/gocheck"
        "github.com/loggo/loggo"

        "launchpad.net/juju-core/state"
        "launchpad.net/juju-core/worker"
    )

Because "launchpad.net/gocheck" will be referenced frequently in test suites,
its name gets a default short name of just "gc".

Testing
=======

`juju-core` uses the `gocheck` testing framework. `gocheck` is automatically
installed as a dependency of `juju-core`. You can read more about `gocheck`
at http://go.pkgdoc.org/pkg/launchpad.net/gocheck. `gocheck` is integrated
into the source of each package so the standard `go test` command is used
to run `gocheck` tests. For example

    go test launchpad.net/juju-core/...

will run all the tests in the `juju-core` project. By default `gocheck` prints
only minimal output, and as `gocheck` is hooked into the testing framework via
a single `go test` test per package, the usual `go test -v` flags are less
useful. As a replacement the following commands produce more output from
`gocheck`.

    go test -gocheck.v

is similar to `go test -v` and outputs the name of each test as it is run as
well as any logging statements. It is important to note that these statements
are buffered until the test completes.

    go test -gocheck.vv

extends the previous example by outputting any logging data immediately, rather
than waiting for the test to complete. By default `gocheck` will run all tests
in a package, selected tests can by run by passing `-gocheck.f`

    go test -gocheck.f '$REGEX'

to match a subset of test names.

Finally, because by default `go test` runs the tests in the current package, and
is not recursive, the following commands are equal, and will produce no output.

    cd $GOPATH/src/launchpad.net/juju-core
    go test

    go test launchpad.net/juju-core

Proposing
=========

All code review is done on rietveld (http://code.google.com/p/rietveld/), not
on launchpad.

Note: If this is your first time using `lbox` you will also be prompted to visit
lauchpad to authorise an oauth token for `lbox`

Once your change is ready, and you have successfully run all the tests you can
propose your branch for merging

    lbox propose

`lbox` will prompt you for a branch description and will create a rietveld code
review for this change, linking it to the launchpad branch, and mailing
reviewers. The `lbox` tool manages the state of the launchpad review, with the
exception of marking reviews as rejected or work in progress by the reviewer.
If you abandon a proposal, you should mark it as rejected in launchpad to avoid
wasting the time of others. If you decide to start again, you should add a
comment to the abandoned rietveld proposal linking it to your replacement.

If your proposal requires additional work, then you can use the `lbox propose`
command again to re-propose, this will also instruct rietveld to mail off any
comments to your reviewers and upload fresh diff.

If your branch requires another branch as a prerequisite use the `-req` flag to
indicate so

    lbox propose -req lp:dave-cheney/add-README

This will produce a diff in rietveld which masks the changes from your prereq.

It is sometimes useful to be able to review your branch in rietveld without
proposing, do to this the `-wip` flag is used

    lbox propose -wip

You can also edit the description of your change with `-edit`. This is useful
when combined with the `-wip` flag to avoid sending too many mails to reviewers
while preparing your proposal.

    lbox propose -edit

By default, lbox creates a new bug in launchpad for each proposed branch, and
assigns the branch to it. If you wish to assign it to an existing bug instead,
use the `-bug` flag to link the branch inside launchpad.

    lbox propose -bug 1234567

There is currently a bug with `lbox` when linking a branch to a bug which sets
the milestone field to the last milestone defined on the project. Generally
this is not what you want, so you should visit the bug's page and correct the
milestone, if set.

Code review
===========

`juju-core` operates on a two positive, no negative review process. You may not
submit your proposal until it has received two LGTM comments. If any NOT LGTM
comments are received, those comments should be resolved to the satisfaction
of the objecting reviewer before submitting. Once your have received at least
two positive reviews, you can submit your branch by going to the launchpad
merge proposal page and:

    - copy and paste the merge proposal description into the
    commit message.
    - mark the proposal as Approved.

The merge proposal will then be tested and merged into trunk assuming
all tests pass cleanly.

lbox hooks
----------

Before proposing, `lbox` runs a number of hooks to improve code quality and
ensure that code is properly formatted. These checks are in
`$GOPATH/src/launchpad.net/juju-core/.lbox.check`. They are run automatically
by `lbox` before proposing or submitting. If these hooks fail you will have
to resolve those errors before trying again. For example

    % lbox propose
    gofmt is sad:

        version/version.go

Dependency management
=====================

In the top-level directory, there is a file, dependencies.tsv, that
holds the revision ids of all the external projects that juju-core
depends on. The tab-separated columns in the file are
the project name, the type version control system used by
that project, and the revision id and number respectively.

This file is generated by running the godeps command (which you
can get with `go get launchpad.net/godeps') on a juju-core
installation with all freshly downloaded directories.

The bash commands used to generate it from scratch are as follows:

    % export GOPATH=/tmp/juju-build
    % go get launchpad.net/juju-core/...
    % go test launchpad.net/juju-core/...
    % godeps -t $(go list launchpad.net/juju-core/...) > dependencies.tsv