Hi Folks!
The best way for all concerned for you to contribute code to SXEmacs
is to set up your own branch with tla. Following are some step by
step instructions as to how to go about that.
I'll start from the point where you have compiled tla and have it
somewhere in your $PATH.
1) Introduce yourself to tla:
$ tla my-id "Joe User <juser@xxxxxxxxxx>" RET
The value you give to `tla my-id' is used in logs and stuff like
that. It _must_ be enclosed in quotes. You can check its value
by running the command again without giving it any value...
$ tla my-id RET
2) Create an archive which will be home to _your_ repo:
$ tla make-archive --signed juser@xxxxxxxxxxxxxxxx \
/path/to/archives/2005/ RET
The `--signed' option is to make your archive a "signed" one. (see 2a
for dealing with GnuPG and tla) This means you'll be GnuPG signing
all commits to your repo. If you don't have GnuPG set up or you
don't want a signed archive, omit this option to make-archive. (All
of my archives are signed).
It isn't mandatory to have a "dated" archive name (the "--2005"
part of "juser@xxxxxxxxxxxxxxxx"), but I use that semantic for my
archives to keep things neat and tidy. One of the SXEmacs
developer's archive name is:
`hroptatyr@xxxxxxxxxxxxxxxxxxxx'
which is just as valid.
The location, `/path/to/archives/2005/' is somewhere that is
writable to _you_. Nobody else needs to have access to this
directory (not even read only access) so it could easily be in
your $HOME. Setting up a "mirror" that _is_ readable to the
outside world (ie, where I can reach it) is the subject of step
3.
The thing to remember about this path is that `archives' _MUST_
exist and `2005' _MUST *NOT*_ exist.
2a) Setting up tla to work with GnuPG (skip this if your archive
isn't signed or you don't wish to verify signed patchsets):
$ mkdir ~/.arch-params/signing RET
$ echo "gpg --clearsign" > ~/.arch-params/signing/\=default RET
$ echo "gpg --verify-files -" > \
~/.arch-params/signing/\=default.check RET
From this point, every commit action will require you to enter
your GnuPG passphrase, you may want to look into a "passphrase
agent". (Sebastian F, could you please comment on this)
3) Mirroring your archive so others (at least, Steve) can reach it:
$ tla make-archive --signed --listing --mirror \
juser@xxxxxxxxxxxxxxxx \
/path/to/internet/accessible/archives/2005/ RET
See step 2 for explanation of `--signed' here.
The `--listing' option enables creating some `.listing' files in
your mirror'd repo's. It makes retrieval of your repo possible
via HTTP without needing stuff like WebDAV. Basically, don't
worry about it, but _DON'T FORGET_ to use this option.
The `--mirror' option means that this archive is a mirror of the
`juser@xxxxxxxxxxxxxxxx' archive. Its name will actually be
`juser@xxxxxxxxxxxxxxxxxxxxxxx'. That leads me to the name...
You _MUST_ use the exact name you used in step 2.
The path, `/path/to/internet/accessible/archives/2005/' is the
path for _you_ to write to the mirror. It _isn't_ the path for
others to read from it. An example...
My repo is accessible to the world at:
http://arch.sxemacs.org/2005/
but _I_ write to it via:
sftp://youngs@xxxxxxxxxxxxxxxx/home/youngs/arch/SXEmacs/2005/
The same applies to this path as for the one in step
2... `archives' _MUST_ exist and `2005' _MUST *NOT*_ exist.
Also, the path you give here _CANNOT_ be the same path as the one
in step 2.
4) Making an archive your default one:
$ tla my-default-archive juser@xxxxxxxxxxxxxxxx RET
This sets the archive to where new repo's (your branch of
SXEmacs) will go. You can check what it is set to at any time
with `tla my-default-archive RET'.
Your default archive is the archive that is used for any tla
operation that you do outside of any working directory and you
don't specify an archive to use.
5) Registering my (Steve's) archive so you can access it:
$ tla register-archive steve@xxxxxxxxxxxxxxxxx \
http://arch.sxemacs.org/2005/ RET
This tells your tla where and how to find my archive.
6) Tagging against my (Steve's) repo and creating your branch:
$ tla tag -S \
steve@xxxxxxxxxxxxxxxxx/sxemacs--main--22.1.1--patch-10 \
sxemacs--branchname--22.1.1 RET
The `-S' option causes tla to create any needed categories,
branches, or versions in your archive.
It's always best to tag against the latest revision of any repo,
and one way to find the latest revision is:
$ tla abrowse steve@xxxxxxxxxxxxxxxxx RET
6a) A note about branch names:
In reality, the name you use for your branch can be anything.
But here are some "don'ts" for SXEmacs branches...
- DON'T use anything vulgar. I won't ever merge in anything
from `sxemacs--fuckyou--22.1.1'.
- DON'T use anything that could be misleading. In other
words, don't call your branch `sxemacs--voice--22.1.1'
unless you are working on some kind of voice or speech
interface to SXEmacs.
- DON'T use anything that could make people think your branch
is the main development branch. For example, don't use any
of these names:
dev, devo, devel, develop, development, main,
mainline, stable.
The easiest thing to do... use your name, or if you are working
on something long-term, use a description of it. For example,
Andrey, you might want to have any (or all) of these:
sxemacs--andrey--22.1.1
sxemacs--anray--22.1.1
sxemacs--freebsd--22.1.1 (only because you are the one
responsible for the FreeBSD SXEmacs package)
7) Getting a working directory of your branch:
$ tla get sxemacs--branchname--22.1.1 sxemacs-branchname RET
That will put a copy of _your_ branch in $PWD/sxemacs-branchname/
8) Updating the contents of your mirror:
$ tla archive-mirror RET
This synchs your mirror archive to your main archive and makes
the changes you've made to your archive accessible to the rest of
the world.
Once you're set up, you might have a hacking cycle a bit like this:
- synch to my repo so you are working from up to date sources
$ cd $WD (working directory)
$ tla star-merge \
steve@xxxxxxxxxxxxxxxxx/sxemacs--main--22.1.1 RET
$ tla commit -s "synch up with the mainline" RET
- create a new log file for documenting the changes you are about to
make:
$ tla make-log RET
This creates a blank log file. Think of it as a ChangeLog file,
but it is only for changes in this particular changeset. Update
the log as you go, or all at once at the end. It doesn't matter,
just do whatever is comfortable for you.
Steve's log file tips:
- log as you go
- be as verbose as you can
- hack hack hack (which obviously includes testing)
- finish up the log
- commit your changes
$ tla commit RET
- synch up your mirror
$ tla archive-mirror RET
- send a commit log/merge request to sxemacs-patches@xxxxxxxxxxx
Creating and Sending the commit log/merge request:
$ tla cat-log patch-n > /tmp/merge-mail RET
$ tla get-changeset patch-n ,,foo-changes RET
$ tla show-changeset --diffs ,,foo-changes >> /tmp/merge-mail
$ mail -s "[merge-req] $(tla logs -f|tail -1)" \
sxemacs-patches@xxxxxxxxxxx < /tmp/merge-mail RET
$ rm -rf ,,foo-changes RET
BTW, a lot of these seemingly mundane tasks can be automated via tla
hooks.
I hope this is helpful and informative. I've tried to go into as much
detail as I could but if you aren't sure on anything, just ask. Oh,
and if anyone can see any blinding errors or omissions, please speak
up.
Have fun, and happy hacking! :-)
Just about to C-c C-c when I remembered... It is possible to convert a
checked out copy of my repo into your own branch...
,----[ taken unashamedly from wiki.gnuarch.org ]
| export branch=project-name--new-branch--1.0 && \
| tla apply-delta $(tla logs -f|tail -n1) \
| $(tla revisions -f $branch |tail -n1) \
| && tla set-tree-version $branch
`----
--
|---<Steve Youngs>---------------<GnuPG KeyID: A94B3003>---|
| In space, |
| No one can hear you rip a stinky |
|------------------------------------<steve@xxxxxxxxxxx>---|
pgp7UFNJofo9d.pgp
Description: PGP signature
|