
		     How to Set Up arch Branches

Let's suppose you want to form local branches of the arch source code
itself.  Perhaps you want to make local customizations, or help
contribute features or bug fixes.  These instructions will get you
started.

These instructions assume that you want to branch from the "latest
sources" of arch -- not necessarily the release versions.  What if you
want to have, instead, local revisions that correspond to particular
releases?   That's the topic of another README.


* Create Categories, Branches, and Versions


arch consists of these packages:



	dists		(root directory of an arch distribution)

		The generic top-level directory for all distributions.
		This project contains the configuration files that
		define meta-projects.  The arch meta project 
		contains these sub-projects:


	arch			./src/arch

		The arch revision control system.

	file-utils		./src/file-utils

		Some basic file utilities for unix-like systems.

	ftp-utils		./src/ftp-utils

		An FTP client library and scriptable client.

	hackerlab		./src/hackerlab

		The hackerlab C library.

	package-framework	./src

		A generic top-level source directory, containing
		Makefiles and configuration scripts that recurse on
		subdirectories and a library of Makefiles and
		configuration scripts for use by those subdirectories.

	text-utils		./src/text-utils

		A collection of basic (plain-)text processing
		utilities.

	shell-utils		./src/shell-utils

		A collection of basic utilities for shell programming.


  You'll need branches of each of those packages.

  The first step is to prepare the archive:


	% cats='dists arch file-utils ftp-utils hackerlab
	        package-framework text-utils shell-utils'

	% for c in $cats ; do
	>   larch make-category $c
	>   larch make-branch $c--devo
	>   larch make-version $c--devo--1.0
	> done

  If you have set up email notification, you should soon receive
  lots of email.  You can verify that those commands took place
  with, for example:

	% larch categories
	arch
	dists
	file-utils
	ftp-utils
	hackerlab
	package-framework
	shell-utils
	text-utils

	% larch branches arch
	arch--devo

	% larch versions arch--devo
	arch--devo--1.0



* Register the regexps.com Archive

  Inform `arch' about the regexps.com archive:


	% larch register-archive lord@regexps.com--2002 \
				ftp://regexps.com/pub/{archive-2002}


  You can verify that with a command such as:

	% larch archives
	...
	lord@regexps.com--2002
		ftp://regexps.com/pub/{archive-2002}
	...

  and

	% larch categories -A lord@regexps.com--2002
	arch
	dists
	file-utils
	ftp-utils
	hackerlab
	package-framework
	piw
	shell-utils
	systas
	text-utils


* Form Branches

  Now to add revisions to your branches which are "tags" from my
  revisions:

	# with `cats' defined as above.
	#

	% for c in $cats ; do
	>   larch tag lord@regexps.com--2002/$c--devo--1.0 $c--devo--1.0
	> done



* Cache Base Revisions

  After tagging from a remote archive, usually you will want to cache
  a full-source copy in your local archive:

	% for c in $cats ; do
	>   larch archive-cache-revision $c--devo--1.0
	> done

  (When tag commands reach the step "finding patches included in
  tagged revision", they take too long.  This will be fixed in a
  future release.)

  Once again, you'll get plenty of email.  In addition, revisions
  will be added to your revision library and browser.

  Take a break at this point -- give the `notify' daemons a chance 
  to load up your revision library.  After that, you'll have very
  fast access to your new branches.


* Check-Out a Project Tree from Your Branches

  Now you should be able to check out arch from your local repository:

	% larch get dists--devo--1.0 arch
	[...]
	% cd arch
	% larch build-config local/devo.arch
	[...]


  After those steps, you can commit changes to your devo branches and
  ask me to consider merging them with my devo branches (you'll need to
  make your archive FTP-accessible).

  Please try to make clean patch sets on branches that you want me to
  look at: make sure that each patch has a focused purpose and a clear
  log message.  Please consider setting up a browser for your
  repository, which will make my patch review process much easier.
  (See README.library).

  One way to help make sure that patches on your "devo" branches are
  neat and tidy is to form separate branches, from your "devo"
  branches, and do day-to-day work there.  Then, when you have a set
  of changes ready, you can merge those changes onto your "devo"
  branches.


# tag: Tom Lord Tue Feb  5 14:37:17 2002 (examples/README.020.branching-arch)
#
