Skip to content
This repository was archived by the owner on Jun 20, 2024. It is now read-only.

WorkingOnWeave

Jump to bottom
Ilya Dmitrichenko edited this page May 7, 2015 · 43 revisions

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 it to a branch in the upstream tree.

Markdown pages live in the subdirectory site/ and CI build 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 commits in any branch on upstream fork a documentation URL would look like:

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

There will also be a pointer to latest commit:

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

For each tag there will be a shorter URL like:

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

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

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.

Updating docs for the latest release

Most user a pointed at the document 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.

Releases

The script ./bin/release is used for releasing the weave distributables. This amounts to pushing new images to DockerHub, and creating a GitHub release and uploading the script to it. The release script looks for the most recent tag matching v* to see what it should build.

To prepare a release, you need to

  • choose a version number, e.g., 0.7.1 (call it $version)
  • add a changelog entry for the new version, at the top of CHANGELOG.md, and commit it
  • tag the repo at that point with v$version (e.g., git tag -a v0.7.1)

You can now do

./bin/release build

which will clone the repo into ./releases/v$version/ and build the images. It also injects version strings into the executables and script so they can be recognised.

To publish a release, in the ./releases/v$version/ dir you need to

  • move the tag latest_release to the same commit as the version tag; e.g., git tag -af latest_release v0.7.1
  • push both the tags to the upstream repo; e.g., git push -f [email protected]:zettio/weave latest_release v0.7.1 (NB if you're testing the release process, remember to push to your own github repo)

You can now publish the release with

./bin/release publish

which will do some sanity checks (like making sure there's not already a release for that version), push the docker images, and create the GitHub release.

Trouble

There's a few things that can go wrong.

  • If the build is wonky, e.g., the tests don't pass, you can delete the directory in ./releases/, fix whatever it is, move the version tag (which should still be only local) and have another go.
  • If the DockerHub pushes fail (which sadly seems to happen a lot), you can just run ./bin/release publish again.
  • If it turns out you released the wrong thing, you can delete the release on github and start again; it's the only thing that has to be manually deleted.
Clone this wiki locally