The FoxtrotGPS project uses Bazaar for version control. Here are a few
basic instructions to help you get started with using it.
Contributing Changes
====================
Overview of the steps:
1. Log in (you only have to do this once on a computer).
2. Create a branch.
3. Edit files, fix your bug or add your change.
4. Commit the files that changed (which only affects your computer).
5. Send the changes to the maintainer, there are several ways to do this.
6. The maintainer(s) will evaluate your change and if they are acceptable,
merge them into the trunk in a timely fashion.
7. Update your source code from the trunk
More details:
1. Log in, using your own email address.
----------------------------------------
bzr whoami "John Doe <jdoe@gmail.com>"
2. Create a branch
------------------
This is almost the same as the first step to building from source.
You should check out code to your own branch. If you are fixing a bug,
name the branch after the bug. This makes it easier to tell
your branch from the trunk when you submit patches.
This is how you might create a branch to fix bug 663102:
bzr branch http://www.foxtrotgps.org/branches/foxtrotgps-dev/ foxtrotgps-663102
cd foxtrotgps-663102
If you are working on a new feature instead of a simple bug fix you might
name the branch after the feature, for example "foxtrotgps-usng-support".
3. Make your change (or addition or whatever)
---------------------------------------------
"One change" means you want to do the minimum necessary to fix just
one bug, not several bugs. This makes evaluating the work you did
easier for the maintainers, and therefore decreases the turn around
time on your changes being incorporated (and increases the probability
that your changes will be accepted!)
It goes without saying, compile and test thoroughly before sending changes in.
If you add a new file to the project use the "add" command:
bzr add newfilename
4. Commit your change
---------------------
Now that you have updated one or more files, you need to commit the
changes. From your source directory, execute the commit command along
with a brief but meaningful message. For example:
bzr commit -m "These changes fix bug number 663102"
NOTE that unlike other version control systems (such as subversion),
when you perform a commit with Bazaar the changes stay on your own
machine. The changes are NOT sent to the remote repository until you
execute a "push" command. Thus you can do many commits and/or reverts
before you share the changes. This makes sense, because if you are
adding a new feature, you have all the benefits of version control
without having to publish any non-working code. It also means you can
work disconnected from a network, pushing changes when you reconnect.
5. Send your changes to the maintainer
--------------------------------------
If the change is relatively small, you can "send" the changes to a
patch file and then attach the file to the bug in the comments section
of the bug tracking system.
The bug tracker is here: https://bugs.launchpad.net/foxtrotgps/
The send-to-a-file command looks like this:
bzr send -o ../fix663102.patch
Now you can use a web browser to connect to the bug tracker and add a
comment to bug 663102, attaching the file fix663102.patch.
If you are working on a big change and you have access to your own
publicly accessible SFTP/Web site, you can use SFTP mode to upload
your changes to your own site, and then share the Web URL with other
developers either by email or through the bug tracker.
6. Wait
-------
After letting us know about your changes, the next step is to wait
for the changes to be accepted and merged into the trunk.
7. Repeat!
----------
To work on a NEW bug or feature, you'd start the whole cycle again,
checking out a new copy of the code so that you are starting from the
trunk.
Publishing with SFTP
====================
To publish code, you need a server that is accessible over the
Internet. Many cheap hosting services (hostmonster.com is one) include
ssh and sftp access. If you have an account at one of these providers,
then all you need do is place a bzr repository on the server in a
space that is accessible by both sftp and http. Then you can directly
publish code with bzr commands, and give the repository http URL to
friends.
If you run a public Web server, and it has the openssh server package
installed, all you need to do is edit its configuration file to enable
sftp access.
More details of setting up an sftp server are really beyond the scope
of this little document. Please don't let access to an sftp server
stop you from participating; let us know and we'll work something out.
Sample SFTP Publish Commands
============================
If you have a domain called mydomain.com the publish command would be
similar to this:
bzr push --create-prefix sftp://jdoe@mydomain.com/~/public_html/branches/foxtrotgps
Bazaar will create the foxtrotgps directory on the remote server and
upload your branch to it.
This example would make your repository accessible to others using
Bazaar with a command like this:
bzr branch http://www.mydomain.com/branches/foxtrotgps
More Help with Bazaar
=====================
The official documentation is online at http://bazaar.canonical.com/
