docs on APACHE_2_0_BRANCH

[Joshua Slive <jo...@slive.ca>]

I have moved the docs-2.0 checkout on httpd.apache.org to the
APACHE_2_0_BRANCH tag so that it will contain the correct docs to go along
with 2.0.  I moved what used to be called docs-2.0 to docs-2.1, but I
haven't yet linked it from anywhere.

Perhaps a link from
http://httpd.apache.org/docs-project/
would be appropriate, but I don't think it is necessary to put it in the
main menu until we get closer to a 2.1 release.

Please scream if there are any problems.

As far as documentation development on this new system, any changes that
are not specific to new features in 2.1 should be made both to HEAD and to
the branch.  If the change is substantial, it might be a good idea to
commit to head first, then wait a few days for feedback before committing
to the branch.  But I don't think we need any strict rules.

Bill R. posted a procedure a little while ago for merging docs changes
back from HEAD into branch.  This may need to be done on a periodic basis
to catch people who forget (or are too lazy) to commit to both places.

Joshua.

Re: docs on APACHE_2_0_BRANCH

[André Malo <nd...@perlig.de>]

* Joshua Slive wrote:

> On Wed, 4 Dec 2002, William A. Rowe, Jr. wrote:
>> At 07:32 AM 12/4/2002, André Malo wrote:
>>>For the 2.0 ist probably too late, but should we consider to create a
>>>directory structure like
>>>
>>>/docs/<version>
>>>
>>>? (<version> == major version aka 2.1, 2.2 etc)
>> Why not create the desired URI structure now, and redirect /docs/, /docs-2.0/,
>> etc.  However, as httpd.apache.org/docs/ are 1.3 today... Perhaps we choose
>> a new nick for the docs (simply /manual/2.0/ etc?) and/or keep the revision
>> as the top-level identifier (e.g. httpd.apache.org/2.0/manual/)?
> 
> I think that if I was starting again today, this is certainly what I would
> do.  But I'm not sure I see the point in switching now.  There are MANY
> inbound links to the various manual pages, and while the redirect would
> keep from them breaking, it will still cause extra round-trips as well as
> problems with search engines, etc.  I personally prefer to keep the URL
> stable.  (But I would not object if a concesus developed to the contrary.)

/manual/<version> makes sense, if the manual is the only version specific 
thing on httpd.apache.org

/<version>/manual/ other way 'round, of course...

I don't see, what else is version specific, but because we don't know about 
the future, I'm +1 for the last scheme:

/2.1/manual/

for the 2.1, etc.

if we're at the point of 2.4 or so, we may start to setup redirects from 
/docs/ and /docs-2.0/ to the new scheme. At 3.2 or 3.4 we may remove the 
old structure completely (410?) and support only the new schemes. (which 
aren't actually *new* at this time... ;-)
IMHO.

nd
-- 
"Eine Eieruhr", erklärt ihr Hermann, "besteht aus einem Ei. Du nimmst
das Ei und kochst es. Wenn es hart ist, sind fünf Minuten um. Dann weißt
du, daß die Zeit vergangen ist."
                             -- Hannes Hüttner in "Das Blaue vom Himmel"

Re: docs on APACHE_2_0_BRANCH

[Joshua Slive <jo...@slive.ca>]

On Wed, 4 Dec 2002, William A. Rowe, Jr. wrote:
> At 07:32 AM 12/4/2002, André Malo wrote:
> >For the 2.0 ist probably too late, but should we consider to create a
> >directory structure like
> >
> >/docs/<version>
> >
> >? (<version> == major version aka 2.1, 2.2 etc)
> Why not create the desired URI structure now, and redirect /docs/, /docs-2.0/,
> etc.  However, as httpd.apache.org/docs/ are 1.3 today... Perhaps we choose
> a new nick for the docs (simply /manual/2.0/ etc?) and/or keep the revision
> as the top-level identifier (e.g. httpd.apache.org/2.0/manual/)?

I think that if I was starting again today, this is certainly what I would
do.  But I'm not sure I see the point in switching now.  There are MANY
inbound links to the various manual pages, and while the redirect would
keep from them breaking, it will still cause extra round-trips as well as
problems with search engines, etc.  I personally prefer to keep the URL
stable.  (But I would not object if a concesus developed to the contrary.)

> >> As far as documentation development on this new system, any changes that
> >> are not specific to new features in 2.1 should be made both to HEAD and to
> >> the branch.  If the change is substantial, it might be a good idea to
> >> commit to head first, then wait a few days for feedback before committing
> >> to the branch.  But I don't think we need any strict rules.
> >
> >At this point a question. Since 2.1 is stated as "development version" what
> >are the docs in HEAD now actually for? 2.1 or 2.2?
> >We also need to change all occuring version numbers "2.0" (in headings,
> >breadcrumb etc.) to appropriate values (2.1 or 2.2 ;-)

The thing in HEAD is 2.1.  It will likely never be released to the public
under that designation.  (When it is ready, it will be called 2.2.)  But
the docs should still say 2.1 while it is in progress.  Yes, all the
headings need to be changed.  Luckily, that is easy with our new system
:-)

> I'm really thinking that (using merges) it's actually easier to maintain docs
> on APACHE_2_0_BRANCH and merge them to head occasionally.  Since
> "new" features are documented on cvs HEAD, all of the other changes will
> merge 'underneath' the latest 'n greatest new stuff.
>
> We could set up some schema where the changes get merged once/week
> (obviously a maintainer is needed, and sometimes conflicts must be resolved.)
> But it is much safer to assume "all these 2.0 changes are also 2.1 changes"
> then visa-versa.

I really don't have enough cvs expertise to know what is best here.
Certainly there will be some pain any way we do it.  But perhaps there is
a benefit to concentrating that pain, so that we don't discourage casual
documenters by making the process too complicated.

My main concern is that when conflicts come up, they won't be one-time
things.  As soon as there is a conflict, it will repeat with every merge,
right?  Or is there some magic way to do this so that you only have to
deal with the conflict once?

Joshua.

Re: docs on APACHE_2_0_BRANCH

["William A. Rowe, Jr." <wr...@apache.org>]

At 07:32 AM 12/4/2002, André Malo wrote:
>* Joshua Slive wrote:
>
>> I have moved the docs-2.0 checkout on httpd.apache.org to the
>> APACHE_2_0_BRANCH tag so that it will contain the correct docs to go along
>> with 2.0.  I moved what used to be called docs-2.0 to docs-2.1, but I
>> haven't yet linked it from anywhere.
>
>Fine.
>
>For the 2.0 ist probably too late, but should we consider to create a 
>directory structure like
>
>/docs/<version>
>
>? (<version> == major version aka 2.1, 2.2 etc)

I'm presuming you are talking about the website?  Since binaries don't
peacefully coexist by default (in apache/bin we have httpd, so 
in apache/manual we have that httpd's docs) and version control should
make things simpler in the long run [short term growing pains, and
changes in strategy aside.]

Why not create the desired URI structure now, and redirect /docs/, /docs-2.0/,
etc.  However, as httpd.apache.org/docs/ are 1.3 today... Perhaps we choose
a new nick for the docs (simply /manual/2.0/ etc?) and/or keep the revision
as the top-level identifier (e.g. httpd.apache.org/2.0/manual/)?


>> As far as documentation development on this new system, any changes that
>> are not specific to new features in 2.1 should be made both to HEAD and to
>> the branch.  If the change is substantial, it might be a good idea to
>> commit to head first, then wait a few days for feedback before committing
>> to the branch.  But I don't think we need any strict rules.
>
>At this point a question. Since 2.1 is stated as "development version" what 
>are the docs in HEAD now actually for? 2.1 or 2.2?
>We also need to change all occuring version numbers "2.0" (in headings, 
>breadcrumb etc.) to appropriate values (2.1 or 2.2 ;-)

I'm really thinking that (using merges) it's actually easier to maintain docs
on APACHE_2_0_BRANCH and merge them to head occasionally.  Since
"new" features are documented on cvs HEAD, all of the other changes will
merge 'underneath' the latest 'n greatest new stuff.

We could set up some schema where the changes get merged once/week 
(obviously a maintainer is needed, and sometimes conflicts must be resolved.)  
But it is much safer to assume "all these 2.0 changes are also 2.1 changes"
then visa-versa.

Bill

Re: docs on APACHE_2_0_BRANCH

[André Malo <nd...@perlig.de>]

* Joshua Slive wrote:

> I have moved the docs-2.0 checkout on httpd.apache.org to the
> APACHE_2_0_BRANCH tag so that it will contain the correct docs to go along
> with 2.0.  I moved what used to be called docs-2.0 to docs-2.1, but I
> haven't yet linked it from anywhere.

Fine.

For the 2.0 ist probably too late, but should we consider to create a 
directory structure like

/docs/<version>

? (<version> == major version aka 2.1, 2.2 etc)

> Perhaps a link from
> http://httpd.apache.org/docs-project/
> would be appropriate, but I don't think it is necessary to put it in the
> main menu until we get closer to a 2.1 release.

ACK.

> As far as documentation development on this new system, any changes that
> are not specific to new features in 2.1 should be made both to HEAD and to
> the branch.  If the change is substantial, it might be a good idea to
> commit to head first, then wait a few days for feedback before committing
> to the branch.  But I don't think we need any strict rules.

At this point a question. Since 2.1 is stated as "development version" what 
are the docs in HEAD now actually for? 2.1 or 2.2?
We also need to change all occuring version numbers "2.0" (in headings, 
breadcrumb etc.) to appropriate values (2.1 or 2.2 ;-)

nd
-- 
Da fällt mir ein, wieso gibt es eigentlich in Unicode kein
"i" mit einem Herzchen als Tüpfelchen? Das wär sooo süüss!
 
                                 -- Björn Höhrmann in darw