Workflow How To

This is the proposed Workflow to be used during the scrum.

Why?

We want to follow a specific workflow because it makes it simpler if everyone follows the same procedure. It's not too hard to follow and it doesn't affect how you actually prefer to code.

The workflow uses mercurial code management tool. Mercurial (or hg) is very similar to SVN which you may have come across before. The point of such a tool is to track changes made to files so that these can be integrated into the central repository - ensuring all your hard work is not lost! By automating much of the process we can focus on code rather than on integrating solutions.

Luckily you dont need to know an awful lot about Mercurial - just follow the commands as described below.

The Process

The process starts right here on BitBucket. Before you begin you will need to have registered a bitbucket account and be logged in.

Fork eventscripts-xa

The first thing you need to do is create your own fork or copy of this project. Head to the project source page and search for a "fork" link near the top of the page (on the right).

Click this and you will be shown a new page asking you to name your project. We advise you to just use eventscripts-xa but you can use whatever you like. For the purposes of this guide we will be assuming eventscripts-xa is the repository name, we'll also assume your bitbucket username is escoder (obviously replace these with your own).

Once you click create on this page your project will be created along with your own copy of the repository.

Pull a local copy

For the next stage you need mercurial installed on your computer. I recommend that you install the command line version rather than the various GUI tools. While they claim to make things easier (especially on windows) it probably complicates the issue.

For Linux something like...

• yum install mercurial
• apt-get install mercurial

Or from source:

wget http://mercurial.selenic.com/release/mercurial-1.4.1.tar.gz 
tar xzf mercurial-1.4.1.tar.gz 
cd mercurial-1.4.1 
sudo python setup.py install 

For Windows download the latest binary and run the installer.

Once installed create a directory for the XA source code and open up a command prompt there.

First step is to clone your copy locally:

hg clone http://www.bitbucket.org/escoder/eventscripts-xa

After a bit of thinking this will create a local copy. Now run:

hg update

and files should appear in your directory. The XA source code is to be found under scripts/main.

Make your changes

Choose what you will be working on from the list in the issue tracker. Click on your selected issue(s) and under "assign to" choose your name. This is important so everyone else knows an issue is being worked on.

You can work on as many issues as you like: however I suggest to do a few at a time to avoid confusion / complexity.

Do your fixes or additions and fully test them. Once your happy commit you changes. First use:

hg status

To check on the files you edited. Anything with a ? next to it is a new file that mercurial isn't tracking. If you created new files then they will appear this way and you need to add them to the repository.

hg add .

Should add ALL of the files. If you have meta stuff such as cfg or project files you must not add these (obviously).

Once your happy everything was added run:

hg commit

Type a commit message that makes sense / means something. i.e. list your changes and additions in a brief summary. You can (and should) commit multiple times when your working.

Once commited and ready you need to "push" changes back to BitBucket.

hg push

Should handle things automagically.

Merge Changes

At intervals when you have fixed a number of bugs/issues and they are successfully committed it is time to merge them back into the main branch. To do this you need to submit a Pull Request to the repository managers.

Use this URL: http://hg.errant.me.uk/eventscripts-xa/pull/ (or visit the main evenscripts-xa repository and click *pull request* at the top of the page).

In the box that appears you should list exactly which issues you have fixed by their issue number - this is crucial. Make sure your forked repository is selected and from the list of usernames tick errant (more names might be added later - check back) to be notified.

Hit submit.

As we receive pull requests we will merge all of your changes into the main repository automatically closing the issues you listed as fixed (this is a semi-complex process, hence leaving it to just a few people to do).

Rinse, Repeat

Once your pull request is submitted you must not push to your BitBucket repository again. However you can continue working and commiting locally on your next set of bug fixes!

However it is advisable to wait till the merge is performed (and someone tells you it worked successfully) then delete your fork (this is done in the admin tab). Finally go back to Step #1 and fork the latest version of the master repository - this is sensible because other fixes and changes might have appeared in the mean tim and you will then be working with the latest code :)

This revision is from 2010-04-28 15:56