1The FoxtrotGPS project uses Bazaar for version control. Here are a few 2basic instructions to help you get started with using it. 3 4 5Contributing Changes 6==================== 7 8Overview of the steps: 9 101. Log in (you only have to do this once on a computer). 112. Create a branch. 123. Edit files, fix your bug or add your change. 134. Commit the files that changed (which only affects your computer). 145. Send the changes to the maintainer, there are several ways to do this. 156. The maintainer(s) will evaluate your change and if they are acceptable, 16 merge them into the trunk in a timely fashion. 177. Update your source code from the trunk 18 19More details: 20 211. Log in, using your own email address. 22---------------------------------------- 23 24bzr whoami "John Doe <jdoe@gmail.com>" 25 262. Create a branch 27------------------ 28 29This is almost the same as the first step to building from source. 30You should check out code to your own branch. If you are fixing a bug, 31name the branch after the bug. This makes it easier to tell 32your branch from the trunk when you submit patches. 33 34This is how you might create a branch to fix bug 663102: 35 36 bzr branch https://www.foxtrotgps.org/branches/foxtrotgps-dev/ foxtrotgps-663102 37 cd foxtrotgps-663102 38 39If you are working on a new feature instead of a simple bug fix you might 40name the branch after the feature, for example "foxtrotgps-usng-support". 41 423. Make your change (or addition or whatever) 43--------------------------------------------- 44 45"One change" means you want to do the minimum necessary to fix just 46one bug, not several bugs. This makes evaluating the work you did 47easier for the maintainers, and therefore decreases the turn around 48time on your changes being incorporated (and increases the probability 49that your changes will be accepted!) 50 51It goes without saying, compile and test thoroughly before sending changes in. 52 53If you add a new file to the project use the "add" command: 54 55 bzr add newfilename 56 574. Commit your change 58--------------------- 59 60Now that you have updated one or more files, you need to commit the 61changes. From your source directory, execute the commit command along 62with a brief but meaningful message. For example: 63 64 bzr commit -m "These changes fix bug number 663102" 65 66NOTE that unlike other version control systems (such as subversion), 67when you perform a commit with Bazaar the changes stay on your own 68machine. The changes are NOT sent to the remote repository until you 69execute a "push" command. Thus you can do many commits and/or reverts 70before you share the changes. This makes sense, because if you are 71adding a new feature, you have all the benefits of version control 72without having to publish any non-working code. It also means you can 73work disconnected from a network, pushing changes when you reconnect. 74 755. Send your changes to the maintainer 76-------------------------------------- 77 78If the change is relatively small, you can "send" the changes to a 79patch file and then attach the file to the bug in the comments section 80of the bug tracking system. 81 82The bug tracker is here: https://bugs.launchpad.net/foxtrotgps/ 83 84The send-to-a-file command looks like this: 85 86 bzr send -o ../fix663102.patch 87 88Now you can use a web browser to connect to the bug tracker and add a 89comment to bug 663102, attaching the file fix663102.patch. 90 91If you are working on a big change and you have access to your own 92publicly accessible SFTP/Web site, you can use SFTP mode to upload 93your changes to your own site, and then share the Web URL with other 94developers either by email or through the bug tracker. 95 966. Wait 97------- 98 99After letting us know about your changes, the next step is to wait 100for the changes to be accepted and merged into the trunk. 101 1027. Repeat! 103---------- 104 105To work on a NEW bug or feature, you'd start the whole cycle again, 106checking out a new copy of the code so that you are starting from the 107trunk. 108 109Publishing with SFTP 110==================== 111 112To publish code, you need a server that is accessible over the 113Internet. Many cheap hosting services (hostmonster.com is one) include 114ssh and sftp access. If you have an account at one of these providers, 115then all you need do is place a bzr repository on the server in a 116space that is accessible by both sftp and http. Then you can directly 117publish code with bzr commands, and give the repository http URL to 118friends. 119 120If you run a public Web server, and it has the openssh server package 121installed, all you need to do is edit its configuration file to enable 122sftp access. 123 124More details of setting up an sftp server are really beyond the scope 125of this little document. Please don't let access to an sftp server 126stop you from participating; let us know and we'll work something out. 127 128Sample SFTP Publish Commands 129============================ 130 131If you have a domain called example.com the publish command would be 132similar to this: 133 134 bzr push --create-prefix sftp://jdoe@example.com/~/public_html/branches/foxtrotgps 135 136Bazaar will create the foxtrotgps directory on the remote server and 137upload your branch to it. 138 139This example would make your repository accessible to others using 140Bazaar with a command like this: 141 142 bzr branch https://www.example.com/branches/foxtrotgps 143 144More Help with Bazaar 145===================== 146 147The official documentation is online at https://bazaar.canonical.com/ 148 149