Branches And Development Process

Weblocks development process occurs in three Mercurial branches - development, stable, and experimental. All branches are hosted by http://www.bitbucket.org. New features are normally pushed to the development branch. The features are tested, improved, and eventually merged into the stable branch. The experimental branch is a Mercurial patch queue based on the development branch. Experimental features are intended to be pushed into this branch as Mercurial queue patches. These patches may later be dropped, or merged into the development branch.

Stable Branch

The stable branch can be browsed at http://www.bitbucket.org/skypher/weblocks-stable/, and cloned by running the command below: 

hg clone http://www.bitbucket.org/skypher/weblocks-stable/

This branch contains well tested code that is suitable for running a production web site. Normally, large bug fixes and new features are merged into the stable branch only after it is extensively tested in the development branch.

Development Branch

The development branch can be browsed at http://www.bitbucket.org/S11001001/weblocks-dev/, and cloned by running the command below: 

hg clone http://www.bitbucket.org/S11001001/weblocks-dev/

This branch contains code that may contain bugs, requires more work, or causes problems with the test suite or other features in the repository. After code is perfected and tested in the development branch it is merged into the stable branch.

Experimental Branch

The experimental patch queue can be browsed at http://www.bitbucket.org/S11001001/weblocks-experimental-queue/, and cloned by running the command below: 

hg qclone http://www.bitbucket.org/S11001001/weblocks-experimental-queue/

This patch queue contains experimental features that might not be included into the Weblocks repository. This is a "sandbox" where such features may be tried out before deciding whether they should be merged into the development branch permanently.

For information on how to use patch queues with BitBucket please see http://ches.nausicaamedia.com/articles/technogeekery/using-mercurial-queues-and-bitbucket-org.

Submitting Patches

Developing and maintaining Weblocks is fun, but it takes a lot of time. I very much appreciate people submitting patches and I'd like to accept as many useful patches as possible, but unfortunately some submissions require me to carve out chunks of time that I do not have. To make the maintenance process easier on me and to increase the likelihood of getting your patch accepted, please follow the guidelines below:

  1. Add a documentation string for every function/class/slot/parameter you're adding. If you're modifying something, please be sure to also modify relevant documentation strings.
  2. Unit test every feature you're adding. If you feel something you've added isn't possible to unit test in a useful manner, let me know about it.
  3. Follow the overall code and documentation style of Weblocks codebase. I know it's not perfect, and one day I may write scripts to change it, but consistency is more valuable than tiny bits of styling perfection.
  4. Integrate your changes into Weblocks codebase.
    1. If you're adding new files, also add them to relevant ASDF files.
    2. Put files in the appropriate location (parts of weblocks under src, unit tests under test, scripts under scripts, publicly downloadable files under pub, etc.) If you're not sure where to put something, ask me.
    3. If you're adding new unit tests, make sure they don't affect the testing environment in a way that may break other tests.
    4. Make sure existing unit tests pass.
  5. To submit the patches please publish your repository clone on http://www.bitbucket.org (or elsewhere) and initiate a pull request on the appropriate branch's BitBucket page. To publish on BitBucket, fork the appropriate Weblocks branch, clone the fork locally, and make all your changes in that clone. Initiate the pull request for the appropriate repository (see branch descriptions above). If you're not sure which branch should be used, please ask on the weblocks group. Detailed BitBucket steps follow.
    1. Log in to bitbucket.org
    2. Go to the appropriate queue, normally http://www.bitbucket.org/coffeemug/weblocks-dev/
    3. Click the "fork" button. Make sure your fork is not a private repository.
    4. Install Mercurial on a machine somewhere; I'll assume you're using the command line interface
    5. Go to your fork in bitbucket; get the Clone URL
    6. Run: hg clone [Clone URL]
    7. Make your edits for the patch you want to submit
    8. Run: hg commit
    9. Run: hg push
    10. Wait a bit, then check your forked repo on bitbucket for the changes
    11. Go back to the main repo on bitbucket.
    12. Click the "Pull Request" button.
    13. Select your forked repo in the dropdown
    14. Explain your changes in the text box
    15. Check all the boxes beside people's names; by default it sends to no-one.
    16. Click send request
    17. Leave the branch in place until the devs say they are done with it