WorkingOnWeave

Outline dev process

We use pull requests to keep as clean a history as possible in the main (weaveworks) repository.

Members of the weaveworks GitHub organisation use branches in the main weaveworks repo. Others fork the main repo into their own repo.

To set things up, add a remote for the main repo. I call mine 'upstream'.

$ git remote add upstream [email protected]:weaveworks/weave
$ git remote set-url --push upstream NO_PUSH

The second line above is to prevent accidental pushes -- you can always reinstate the regular URL, for special circumstances, or use the repo URL directly.

In practice this means:

• work on feature branches for all but the simplest most uncontroversial changes
• before you start a feature branch, make sure the branch you're branching from (probably master) is up to date with the main repo; e.g.,

$ git checkout master
$ git fetch upstream master
$ git merge --ff-only upstream/master
$ git checkout -b issuenum_feature_branch

• before you submit a PR, make sure it's likely to merge cleanly, ideally as a fast-forward, to the main repo. This may involve a rebase; e.g.,

$ git fetch upstream master
$ git rebase upstream/master

Also, run all the smoke-tests in the weave/test directory.

This invariant should hold:

• you can always fast-forward your master to upstream/master

Finally, please make sure you gofmt your code before submission. See this blog article for information on invoking gofmt from your IDE or editor of choice, or as a preventative pre-commit hook.

All PRs are reviewed by at least one member of the weaveworks org.

In weave, PRs are merged by the reviewer, not the author.

Co-operating on feature branches

If co-operating on a feature branch, try to minimise the possibility of 3-way merges by only pushing when you can fast-forward. In essence, this means a similar workflow to the above: fast-forward onto the remote, do work, fetch and rebase if necessary, push.

Contributors may chose to keep feature branches in the main repository to ease collaboration, or to avail themselves of the CI system. In this case, the following convention is used for branch naming:

issues/<issue-number>-short-descriptive-text

For example:

issues/984-register-dns-resolver

Rationale: issues is used as a namespace to group feature branches in the main repo so they may be distinguished from other types of branch; use of the directory separator is transparent to git for this purpose, leaving userspace tools to represent the hierarchy as they see fit

Please remember to remove such branches from the main repo once they are merged - there is a handy button on the GitHub UI for this purpose.

Working on docs

Docs are built automatically in CI (Travis at the time of writing) and published in CDN (Google at the time of writing).

You can configure Jekyll on your development machine (see below), but you can also just push to a branch in the upstream tree.

Markdown pages live in the subdirectory site/. CI builds and publishes the docs on branch and tag pushes. Potentially you should be able to find docs for every revision that appeared in upstream.

URL scheme

For each commit in any branch on an upstream fork a documentation URL would look like:

http://docs.weave.works/weave/<branch>/<commit>/[index.html]

There are also redirect to the latest commit:

http://docs.weave.works/weave/<branch>/[index.html]

For each tag there is a shorter URL like:

http://docs.weave.works/weave/<tag>/[index.html]

And for each branch head there is a shorter URL like:

http://docs.weave.works/weave/master/head/[index.html]

The place to find the latest development documentation is: docs.weave.works/weave/master/head

Looking at doc changes locally

Install Jekyll as described here (use the "bundle method"): https://help.github.com/articles/using-jekyll-with-pages/#installing-jekyll

This amounts to:

site$ gem install bundler
site$ bundle install

It may fail on compiling redcarpet; if so, you probably need the ruby-dev package (ruby-devel on Fedora).

You may also need to install a JavaScript engine, e.g. Node.js.

Now you can see the site on http://localhost:4000/ by running

site$ bundle exec jekyll serve --watch

You can leave it running, it will watch for file changes and rebuild.

Release process

See here

Updating docs for the latest release

Most user are pointed at the documentation for latest_release tag, which sometimes requires cosmetic changes. The CI script will pick up such changes from a special branch latest_release_doc_updates, you just need to commit or cherry-pick and push those changes manually.