@need 3200

@node Starting a New Project
@chapter Starting a New Project

@geindex make-category

@geindex make-branch

@geindex make-version

@geindex categories

@geindex branches

@geindex versions



This and later chapters will show you how to set up and manage a 
simple project with @code{arch} through the specific example of a @geindex hello
world
@dfn{hello
world} program.

@need 3200

@section Create a Project Category

As a first step in the @code{hello-world} project, create a new @geindex project
category
@dfn{project
category} in the archive:

@example
@group
        % larch make-category hello-world
@end group
@group
@end group
@end example

You can verify that that worked by asking for a list of all the
categories in your archive:

@example
@group
        % larch categories
        hello-world
@end group
@group
@end group
@end example



@need 3200

@section Create a Project Branch

@code{arch} encourages you to divide up the work on a project into 
separate @geindex branches
@dfn{branches}.   


Roughly speaking, branches are a mechanism for splitting the work on a
project into two or more, largely independent efforts.  Let's suppose,
for example, that the @code{hello-world} project has two needs:


1) A need to make regular releases of good ol' fashioned @code{hello-world},
fixing simple bugs, porting the program, and adding tiny features.


2) A need to begin work on a graphical user interface for
@code{hello-world,} which is expected to take about a year to complete.


We'd like those two efforts to proceed in parallel, but not get in
each others way.   For example, we don't want GUI code to appear in
the regular releases until it is working fairly well.


In such a case, we'll use branches: one for regular releases (the
@emph{mainline} branch) and another for GUI features (the @emph{gui} branch).


There are many other uses for branches, some of which will be
described later in the manual.   For now, we just need one branch: a
branch for the official latest sources of @code{hello-world}:

@example
@group
        % larch make-branch hello-world--mainline
                            ^^^^^^^^^^^  ^^^^^^^^
                                |            |
                                |       branch name
                          category name
@end group
@group
@end group
@end example

Notice that the category and branch names are separated by two dashes.
In general, category and branch names must consist only of letters and
dashes, must begin with a letter, must not themselves contain two
dashes, and must not end with a dash.


As usual, it's easy to verify that the command worked by asking for a 
list of branches in the @code{hello-world} category:

@example
@group
        % larch branches hello-world
        hello-world--mainline
@end group
@group
@end group
@end example



@need 3200

@section Choose a Version Number

Finally, you must choose a version number for the version of
@code{hello-world} that you'll be working on, and create that version
in the archive.


Version numbers in @code{arch} are @emph{not} the name of a particular
"snapshot" or release of your project -- though they are related to
that concept.   Instead, version numbers are the name of a
@geindex development line
@dfn{development line}: a sequence of changes that you make while creating 
a particular release.


You start a new development line within a branch as in this example:

@example
@group
        % larch make-version hello-world--mainline--0.1
                                                    ^^^
                                                     |
                                          version number
@end group
@group
@end group
@end example

Notice that version numbers are always two positive integers,
separated by a period.   These are sometimes called the @emph{major} and
@emph{minor} version.


You can verify the new version by asking what versions exist within
your branch:

@example
@group
        % larch versions hello-world--mainline
        hello-world--mainline--0.1
@end group
@group
@end group
@end example



@need 3200

@section Why is it Like This

People new to @code{arch} are sometimes startled at the rigidity of its
archive structure.   Two common questions (and their answers) are:


@strong{Why have categories, branches and versions?  Why can't I just name my
projects with arbitrary string?} These questions are best answered by
recalling that a revision control system is a @emph{librarian}.  Part of
its job is to help people navigate and search through very large
collections of projects and source code.  In order to make such
searching practical, @code{arch} defines a @emph{cataloging system}: categories,
branches, and versions.   (See @strong{What is Revision Control?} in @ref{Introducing arch}.)


This is somewhat analogous to the cataloging systems used in libraries
for books, such as the Dewey decimal classification system: it's a
hierarchical categorization of everything in the library.  It's a
uniform way to describe where a given item is stored, and it aids
searching by suggesting the relationships between various items.  For
example, a branch is likely most closely related to other branches in
the same category.  A version with a higher major version number most
likely contains later work than one in the same branch with a lower
major version number.


The analogy isn't perfect:  book cataloging systems such as Dewey are
based on an official list of categories and subcategories, while
@code{arch}, on the other hand, let's you choose your own category names.  
Still, like Dewey, @code{arch} names are based on the idea of grouping
related items together to make them easier to search and navigate.
And just as Dewey is intended to capture the most common patterns of
how people search through books, @code{arch} is intended to capture the
most common patterns of how people search through source archives.


@strong{Why have two-component version numbers?} Some people do not like the
limitation of @code{<major>.<minor>} version numbers: instead of @code{0.1}
they'd prefer @code{0.1.1}, for example.


This limitation may, in fact, eventually be removed from @code{arch}.  For
now, though, the uniformity of two-component version numbers makes it
easier to sort an arbitrary list of @code{arch} version numbers using the
standard unix program @code{sort}.   Ease of integration with standard
tools such as @code{sort} is a high priority for @code{arch}.




@need 3200

@section How it Works -- Creating Categories, Branches, and Versions

What do the commands @code{make-category}, @code{make-branch}, and
@code{make-version} actually do?  It's conceptually quite simple:  they
create new directories in your archive:

@example
@group

@end group
@group
        % larch whereis-archive lord@@emf.net--2003-example
        /home/lord/@{archives@}/2003-example
@end group
@group

@end group
@group
        % cd `larch whereis-archive lord@@emf.net--2003-example`
@end group
@group
@end group
@end example

Categories are top level directories:

@example
@group
        % ls
        =meta-info      hello-world
@end group
@group
@end group
@end example

Branches the next level:

@example
@group
        % ls hello-world
        =README         hello-world--mainline
@end group
@group
@end group
@end example

Versions the third:

@example
@group
        % ls hello-world/hello-world--mainline
        =README         hello-world--mainline--0.1
@end group
@group
@end group
@end example

Versions are themselves directories:

@example
@group
        % ls hello-world/hello-world--mainline/hello-world--mainline--0.1/
        +revision-lock  +version-lock   =README
@end group
@group
@end group
@end example

@strong{Note:} The @code{=README} files contain information about who created the
category, branch, or revision and when.  These are the @emph{sole}
exception to the usual rule that you should never edit files in an
archive by hand.   You can add new, arbitrary text to those files
after the header fields they contain, separated from the headers by
a blank line.   You should not, however, alter the header fields.


@strong{Note:} The lock files (e.g. @code{+revision-lock}) are used internally by
arch.  When adding new data to an archive, @code{arch} doesn't simply call
@code{mkdir}.  Instead, it carefully modifies archives to that they are
always in a consistent state, regardless of what commands are issued
concurrently, or whether or not a command is killed in mid-execution.







