To: new-httpd@hyperreal.com
Subject: Re: Documentation
References: <Pine.HPP.3.95.961101200801.16700A-100000@ace.nueva.pvt.k12.ca.us>
From: Paul Richards <p.richards@elsevier.co.uk>
Date: 04 Nov 1996 17:50:45 +0000
In-Reply-To: Alexei Kosut's message of Fri, 1 Nov 1996 20:10:55 -0800 (PST)
Message-ID: <57sp6ppx56.fsf@tees.elsevier.co.uk>
Lines: 57
Sender: owner-new-httpd@apache.org
Precedence: bulk
Reply-To: new-httpd@hyperreal.com

Alexei Kosut <akosut@nueva.pvt.k12.ca.us> writes:

> No, it is very much not redundant. Nothing is. 1.0 contains the old
> Apache 1.0 docs. The top-level /docs/ directory contains the Apache
> 1.1 docs, 1.1 contains the whats-new-in-Apache 1.1 docs, 1.2 contains
> the whats-new-in-Apache 1.2 docs. When Apache 1.2 goes from beta to
> final, the top-level will change to contain complete 1.2 docs, and the
> existing 1.1 docs will be shunted into docs/1.1 (I don't know what
> will happen with the existing docs/1.1 - I never really thought about
> it at the time).

I'm sure I commented on this some time ago but I obviously didn't
shout loud enough.

The apache-docs cvs tree is already a mess and we haven't started
yet. This is definately not the way to use cvs to your advantage.

The 1.0 docs should have been commited into the /docs directory first
and then it should have been tagged. The 1.1 docs should then have
been overlayed and committed with a new tag. Likewise for 1.2. once
the initial commit of our current docs are done then things would
proceed as follows.

There are doc tags that are in sync with the releases, i.e. when the
src gets tagged for a release then that tag is placed on the docs as
well. When a release takes place the doc tree is branched the same as
the main tree.

The last release is tarred up and released (including the docs I'd
hope) and then development takes place on the head, including working
on the docs.

Updates of the live web site can be done in a few ways. You can update
the web site every x hours by doing an export or you can do an export
by hand when the docs seem to have changed enough. On the web site you
maintain multiple directories for each version so all the docs for
each release are available on the web server. You check out into those
directories using the tags that were placed on the cvs tree. This
works well, you have a single lineage of the docs in cvs, at release
time the taggin/branching works as it does for the sources and you can
keep all the docs for old versions available online without any
problems.

> One note - the CVS messages for manuals/ should most defenitely be
> sent to apache-docs instead of (or at least as well as) apache-cvs. I
> see no reason for the docs-only people (well... person) on apache-docs
> to have to suffer through all the source-related CVS updates simply to
> get the docs-related ones.

This is a good idea, we do this for FreeBSD, if I get free time before
Ben does I'll look into it.

-- 
  Paul Richards. Originative Solutions Ltd.  (Netcraft Ltd. contractor)
  Elsevier Science TIS online journal project.
  Email: p.richards@elsevier.co.uk
  Phone: 0370 462071 (Mobile), +44 (0)1865 843155