SubMaster
From RockWiki
Contents |
What is SubMaster?
SubMaster is a system for distributed software development, based on Subversion. SubMaster has two more or less independent parts:
The SM Command Line Tool (sm)
This is a small tool which enables the user to create a local copy of a remote subversion repository and make changes to this local repository. SM can also be used to create patches and send them back upstream as well as synchronizing the local repository with changes in the original tree.
There also exists a small shell script (smap.sh) for the maintainer of the official tree to apply patches easily.
SM requires: Subversion 1.2.3 or later, Perl, patchutils 0.2.31 or later, w3m and curl, as well as several CPAN packages (cpan-svn-mirror, cpan-svn-simple, cpan-uri).
The SubMaster Server Side
Is a web application written in www.clifford.at/spl" rel="nofollow">WebSPL for managing the patches created by various contributors. But it does not enforce the useage of the Submaster client - patches are accepted whether they are created using submaster or not.
SubMaster can be downloaded from this subversion repository. The ROCK Linux SubMaster server can be reached here.
Clifford's SubMaster paper and presentation for SANE 2004 can be found www.clifford.at/papers/2004/sm/" rel="nofollow">here. Note that the first version of the SubMaster server side was written in Perl, and has been completely rewritten in WebSPL following CLT 2006.
A quick introduction to using SubMaster
First install SM and create your local repository:
# wget -O /usr/local/bin/sm https://www.rocklinux.net/svn/submaster/trunk/sm.pl # wget -O /usr/local/bin/smap https://www.rocklinux.net/svn/submaster/trunk/smap.sh # chmod +x /usr/local/bin/sm /usr/local/bin/smap # sm create svn://www.rocklinux.net/rock-linux/trunk rock
This will create the directory rock which will contain your working copy and rock.sm which will contain the patches, databases and all the rest.
You also need svm and two other CPAN packages:
# rocket emerge cpan-svn-mirror # rocket emerge cpan-svn-simple # rocket emerge cpan-uri
Or alternatively using the CPAN shell:
# cpan ... cpan> install SVN::Mirror
If you have registered at the SubMaster server, you want to let SM know how to communicate with the server. Edit the file rock.sm/SM/server.txt and add:
https://www.rocklinux.net/submaster <username> <password>
After that, just work with the rock/ tree as if it were a normal svn working copy (well - it is one ;-). Edit files as you want, add new files with svn add, etc. The Subversion Handbook is a good introduction to Subversion.
Instead of committing changes with svn commit, commit them with sm commit. That will do a standard svn commit and add your changes to the 'send this stuff upstream' queue.
When you have finished and tested a set of changes, you can list your queue with:
# sm queue r44 | root | 2004-01-10 12:10:58 +0100 (Sat, 10 Jan 2004) | 3 lines Added package oprofile. ------------------------------------------------------------------------ r51 | root | 2004-01-10 13:34:35 +0100 (Sat, 10 Jan 2004) | 3 lines Oprofile: don't run depmod. ------------------------------------------------------------------------
And then create a patch by listing the local changes which together form the complete patch:
# sm patch 44 51 Dumping diff for revision 44 ... Dumping and merging diff for revision 51 ... Writing patch to rock.sm/040110_135022_19822.patch ...
Now the patch is sitting in your rock.sm directory waiting to be sent. Just type
# sm send 040110_135022_19822
to send this particular patch or simply
# sm send
to send all pending patches to the server. Btw. a list of pending patches can be viewed with sm patch. It's also possible to synchronize your local tree with the main tree with
# sm sync <resolve-conflicts-if-any> # svn commit -m "SM Sync"
Note that the svn merge mechanism is usually smart enough to not trigger any conflicts if your patch has been applied and is then merged back into your tree. But a conflict can be created if e.g. upstream changes are made to your patch before applying it.
The Web Interface
The web interface is optimized for w3m and can be opened easily from the command line with:
# sm admin
So no need to run X11 to use the submaster server.
A few words about the web interface:
- The "Notes" which can be attached to patches are not a message board! Discussion should always happen on the mailing lists.
- Only use the Notes feature to (a) make remarks which don't lead to discussion, (b) point to other patches (i.e. alternative implementations, etc.) or (c) to add some commands for the SubMaster Server Side Scripts.
- Don't vote against patches without starting a discussion on the mailing list about it.
Please start using it and send feedback to clifford@clifford.at.
How do I ...
Test a set of changes and recommend them for being applied?
First you need to create a clean export of the trunk sources:
# svn export https://www.rocklinux.net/svn/rock-linux/trunk/ rock-test # cd rock-test
next you need to create an smap.cfg file so smap knows where to download the patches from:
set -- -C -S -a journal.txt "$@" URL=https://www.rocklinux.net/submaster
now you can apply all the patches you want to test to the sources:
# smap 2004011100562031731 # smap 2004020903014019880 # smap 2004020903240523744 ...
When you are finished, build appropriate targets and check if everything is working as expected. If the results are satisfactory, send the journal.txt file and a short description of what you have tested to the mailing list. Use the marker "[JOURNAL]" in the subject line for such mails.
Change an already sent but not yet applied patch?
First find the ID of the patch which is already online. Open the web interface in your favorite browser or simply type sm admin. Discard the old patch in the web interface and download it afterwards: (it is not truly deleted, so can still be downloaded)
# sm get 2004011112353408668 Getting 2004011112353408668.patch... https://www.rocklinux.net/submaster/data/2004/01/1112353408668.patch ---
The patch is already applied in your working tree - so you don't need to apply it again.
Just make your changes as usual and apply them:
# sm commit Sending ..... Transmitting file data . Committed revision 82.
Now you can create a patch containg the old changes plus your additional modifications:
# sm patch 2004011112353408668.patch 82 Dumping 2004011112353408668.patch ... Dumping and merging diff for revision 82 ... Writing patch to rock.sm/040112_111941_24274.patch ...
And now you can send your new patch to the server with sm send.
Editors note: If all this sounds confusing, as it did to me, here is a snippet of an email from the users list explaining it:
the scheme is : 1. Discard patch $id in submaster (assuming $id is patch's id) 2. sm get $id (to retrieve the patch) 3. <make some changes and sm commit them> (it creates a new revision $rev) 4. sm patch $id.patch $rev (to create the new patch) 5. sm send (to upload the new patch in submaster) hoping i could make it clearer, mathieu
That seems much clearer, thank you Mathieu.
