
The ``repo`` development tool makes it simple to support a complex workflow
while contributing Pull Requests (PRs) to someone else's upstream mercurial
repositories on bitbucket <http://www.bitbucket.org>.

Upstream maintainers:

- often prefer the PRs **not** to be on branches, as these clutter
  their repository (even when closed at some point).
- not to consist of too many commits/changesets.
- ask you to make additional changes, forcing multiple changesets and possible
  recreation of a new PR

Which collides with the practise of committing often during development.

-----

``repo`` suports starting development on an upstream repository by:

- fast cloning of the **upstream** project to the local work area. A ``pull``
  gets you all the upstream changes, no need to ``SYNC`` your fork on Bitbucket
  first.
- automatic setup a default push target on your own mercurial server

After that you start developing on a (new) branch and commit as often as you
like. Whenever you have time pull and merge with
the ``default`` branch.

``repo`` helps you prepare the PR with a single command by:

- pull from upstream and merge with default
- creating a fresh fork on Bitbucket, named after the branch
- fast fork clone that fork in a work area
- grafting the differences of all your commits on the work area
- (planned: re-running tests)
- commit and push the changes to your fork on Bitbucket

Any problems during previous steps will stop the process, e.g. if the merge
failed.

The only thing that remains, is actually creating the PR on Bitbucket using
the web interface. At which time you can do a final visual inspection of your
changes against upstream.
