WorkingOnWeave

Outline dev process

Everyone has their own fork, and we use pull requests to keep as clean a history as possible in the main (zettio) repository.

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

$ git remote add upstream [email protected]:zettio/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 in your own fork 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.

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.

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.