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

WorkingOnWeave

Jump to bottom
rade edited this page Feb 3, 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

This invariant should hold:

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

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

You will need a local gh-pages branch (due to the way the script is written); run the following once:

git fetch upstream gh-pages
git branch --track gh-pages zettio/gh-pages

Thereafter, use the scripts ./bin/merge-into-gh-pages and ./bin/publish-gh-pages after merging a pull request; don't do anything "manually" in the gh-pages branch.

The github pages site lives in the subdirectory site/, and you can update documentation there. It won't appear on the site, however, until changes have been merged into gh-pages and pushed to the main repo. Since these steps need to be done with quite specific options and arguments, there is a script for each: ./bin/merge-into-gh-pages and ./bin/publish-gh-pages respectively.

The merge into gh-pages should happen when a PR is merged, though it is only strictly necessary if files in site/ have changed. In principle this could be done automatically, but we're doing it manually for now.

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$ cat >> Gemfile
source 'https://rubygems.org'
gem 'github-pages'
^D
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

Be aware that some links may go to the public site, so watch the address bar.

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