4
Before contributing to `juju-core` please read the following sections describing
5
the tools and conventions of this project. This file is a companion to README
6
and it is assumed that file has been read prior.
11
juju-core uses bzr for source control. To make the bzr branching strategy more
12
palatable for the go toolset `juju-core` recommends using the `cobzr` helper.
13
`cobzr` allows the user to juggle multiple branches in place in a way that is
14
compatible with GOPATH. While it is possible to manage bzr branches manually,
15
the remainder of this document will assume cobzr is in use as practiced by the
20
go get launchpad.net/cobzr
22
TODO(dfc) document PPA version
24
It is recommended to use alias `cobzr` to `bzr`.
28
As `cobzr` passes any options it does not handle to `bzr`, it is safe, and recommended
29
to add this alias command to your login shell.
34
`juju-core` uses `lbox` for code review and submission. In addition `lbox` enables
35
the use of prerequisite branches.
39
go get launchpad.net/lbox
41
TODO(dfc) document PPA version
46
All changes to `juju-core` must be performed on a branch, that branch reviewed,
47
then submitted. An overview of the commands used to do so follows. These
48
examples use the `bzr` command, which is assumed to be aliased to `cobzr`, as
49
described above. It is also assumed that your working directory is
50
$GOPATH/src/launchpad.net/juju-core.
52
First, create a branch for your change using the following command
54
bzr branch lp:juju-core/ add-CONTRIBUTING
56
This will branch `juju-core` and create a new branch called `add-CONTRIBUTING` in
57
your local workspace. Importantly this will not switch to this branch immediately,
58
so to switch to this branch use the following
60
bzr switch add-CONTRIBUTING
62
At this point your previous branch will be stashed and the working copy updated
63
to match the state of the `add-CONTRIBUTING` branch. You must ensure any
64
outstanding changes to the previous branch are committed or reverted to avoid
67
You can also list any branches you are currently working on by
75
Import statements are grouped into 3 sections: standard library, 3rd party
76
libraries, juju-core imports. The tool "go fmt" can be used to ensure each
77
group is alphabetically sorted. eg:
84
gc "launchpad.net/gocheck"
87
"launchpad.net/juju-core/state"
88
"launchpad.net/juju-core/worker"
91
Because "launchpad.net/gocheck" will be referenced frequently in test suites,
92
its name gets a default short name of just "gc".
97
`juju-core` uses the `gocheck` testing framework. `gocheck` is automatically
98
installed as a dependency of `juju-core`. You can read more about `gocheck`
99
at http://go.pkgdoc.org/pkg/launchpad.net/gocheck. `gocheck` is integrated
100
into the source of each package so the standard `go test` command is used
101
to run `gocheck` tests. For example
103
go test launchpad.net/juju-core/...
105
will run all the tests in the `juju-core` project. By default `gocheck` prints
106
only minimal output, and as `gocheck` is hooked into the testing framework via
107
a single `go test` test per package, the usual `go test -v` flags are less
108
useful. As a replacement the following commands produce more output from
113
is similar to `go test -v` and outputs the name of each test as it is run as
114
well as any logging statements. It is important to note that these statements
115
are buffered until the test completes.
119
extends the previous example by outputting any logging data immediately, rather
120
than waiting for the test to complete. By default `gocheck` will run all tests
121
in a package, selected tests can by run by passing `-gocheck.f`
123
go test -gocheck.f '$REGEX'
125
to match a subset of test names.
127
Finally, because by default `go test` runs the tests in the current package, and
128
is not recursive, the following commands are equal, and will produce no output.
130
cd $GOPATH/src/launchpad.net/juju-core
133
go test launchpad.net/juju-core
138
All code review is done on rietveld (http://code.google.com/p/rietveld/), not
141
Note: If this is your first time using `lbox` you will also be prompted to visit
142
lauchpad to authorise an oauth token for `lbox`
144
Once your change is ready, and you have successfully run all the tests you can
145
propose your branch for merging
149
`lbox` will prompt you for a branch description and will create a rietveld code
150
review for this change, linking it to the launchpad branch, and mailing
151
reviewers. The `lbox` tool manages the state of the launchpad review, with the
152
exception of marking reviews as rejected or work in progress by the reviewer.
153
If you abandon a proposal, you should mark it as rejected in launchpad to avoid
154
wasting the time of others. If you decide to start again, you should add a
155
comment to the abandoned rietveld proposal linking it to your replacement.
157
If your proposal requires additional work, then you can use the `lbox propose`
158
command again to re-propose, this will also instruct rietveld to mail off any
159
comments to your reviewers and upload fresh diff.
161
If your branch requires another branch as a prerequisite use the `-req` flag to
164
lbox propose -req lp:dave-cheney/add-README
166
This will produce a diff in rietveld which masks the changes from your prereq.
168
It is sometimes useful to be able to review your branch in rietveld without
169
proposing, do to this the `-wip` flag is used
173
You can also edit the description of your change with `-edit`. This is useful
174
when combined with the `-wip` flag to avoid sending too many mails to reviewers
175
while preparing your proposal.
179
By default, lbox creates a new bug in launchpad for each proposed branch, and
180
assigns the branch to it. If you wish to assign it to an existing bug instead,
181
use the `-bug` flag to link the branch inside launchpad.
183
lbox propose -bug 1234567
185
There is currently a bug with `lbox` when linking a branch to a bug which sets
186
the milestone field to the last milestone defined on the project. Generally
187
this is not what you want, so you should visit the bug's page and correct the
193
`juju-core` operates on a two positive, no negative review process. You may not
194
submit your proposal until it has received two LGTM comments. If any NOT LGTM
195
comments are received, those comments should be resolved to the satisfaction
196
of the objecting reviewer before submitting. Once your have received at least
197
two positive reviews, you can submit your branch with `lbox`
204
Before proposing, `lbox` runs a number of hooks to improve code quality and
205
ensure that code is properly formatted. These checks are in
206
`$GOPATH/src/launchpad.net/juju-core/.lbox.check`. They are run automatically
207
by `lbox` before proposing or submitting. If these hooks fail you will have
208
to resolve those errors before trying again. For example
added
removed
CONTRIBUTING
