You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Rodent of Unusual Size <Ke...@Golux.Com> on 2000/05/29 17:37:00 UTC
Web server docs proposal (take n)
Okey, here's another attempt, now that I have some time to write
it up.
What:
I propose to create new CVS modules on the Apache system,
and move the existing server documentation into them and out
from under the source modules.
Why:
Because we have lots of people who are interested in contributing
to the Web server project by working on the docs rather than the
code. This includes people who want to provide translations for
various of the pages. Currently the only way they can do this is
by submitting a patch to the development mailing list, with no
assurance that it won't get ignored. Putting the documentation
into a separate module means we can have a separate -- and less
restrictive, perhaps -- list of people who can commit to the
documentation project.
How:
I propose that two new modules, httpd-docs-1.3 and httpd-docs-2.0,
be created. The current src/htdocs/ directory trees in the apache-1.3
and apache-2.0 CVS modules, and the apidoc/ tree in the apache-devsite
module, would be tagged, and then the files in those trees either
copied or moved to the appropriate httpd-docs-* tree. I suggest
that the address to which CVS updates are sent should include both
the apache-docs list and the apache-cvs list, so people working on
the source are kept apprised of changes to the documentation tree,
but those working only on the docco can see the changes without also
having to see all the source changes. Anyone who wants to see both
can, of course, subscribe to the apache-cvs list.
At some point the htdocs/ subtrees would be removed from the
source trees. That can either be immediate or happen sometime
after there is sufficient comfort that the new model is stable
(possibly some time t after the first release done according to
the new how-to-release instructions).
Concerns and other items:
o The how-to-relase document would need to be updated to include
instructions for extracting the docco module.
o Any time a new committer is added to the source module, it needs
to be added to the docco modules as well.
o Why two modules rather than one with branches? For simplicity and
for parity with the source trees whose contents they track.
o Why the "httpd-" module names instead of "apache-"? Because
'Apache' now means a lot more than just the Web server project,
and 'httpd' has been selected as the name of that project itself.
Whether the existing 'apache-*' modules will get renamed to
'httpd-*', or will remain with their current legacy names, is
a separate issue -- but new modules should, I think, follow the
now-current naming conventions.
o Why separate modules rather than finding a way to let these
docco-only people work only in the htdocs/ subtree? Because of
the mailing list issue, because this is how we've historically
managed disjoint committer lists, because this is how other
ASF projects seem to be handling subprojects, and because this
doesn't require futzing with the CVS scripts that affect *all*
of the ASF projects.
Have I missed anything?
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: Web server docs proposal (take n)
Posted by Rich Bowen <rb...@rcbowen.com>.
Rodent of Unusual Size wrote:
>
...
> What:
> I propose to create new CVS modules on the Apache system,
> and move the existing server documentation into them and out
> from under the source modules.
Not that my vote counts for anything, but as one of the people that
would like to contribute to the documentation, +1 from me on this.
Rich
--
Director of Web Application Development - The Creative Group
http://www.cre8tivegroup.com/
Author - Apache Server Unleashed - http://apacheunleashed.com/
Re: Web server docs proposal (take n)
Posted by Rich Bowen <rb...@rcbowen.com>.
Rodent of Unusual Size wrote:
>
...
> What:
> I propose to create new CVS modules on the Apache system,
> and move the existing server documentation into them and out
> from under the source modules.
Not that my vote counts for anything, but as one of the people that
would like to contribute to the documentation, +1 from me on this.
Rich
--
Director of Web Application Development - The Creative Group
http://www.cre8tivegroup.com/
Author - Apache Server Unleashed - http://apacheunleashed.com/
RE: Web server docs proposal (take n)
Posted by Lars Eilebrecht <la...@hyperreal.org>.
According to Rodent of Unusual Size:
> What:
> I propose to create new CVS modules on the Apache system,
> and move the existing server documentation into them and out
> from under the source modules.
+1
ciao...
--
Lars Eilebrecht - What's another word for "thesaurus"?
lars@hyperreal.org (Steven Wright)
Re: Web server docs proposal (take n)
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
"William A. Rowe, Jr." wrote:
>
> I have a simple question on this last item. For docco folks to be
> effective, don't they need to at least watch the comments to the cvs
> source list so they catch 'things that need new documentation'?
Only those that are writing new documentation. Most of the volunteers
we have word from aren't doing that; they want to reword things,
make them consistent, clarify them, and/or translate them to other
languages. Everyone will be encouraged to watch the source cvs list,
but it's hardly necessary for some of them.
Unfortunately, our timing was rather bad; I was apparently making
the changes while you were writing your mail. Right now, here's
how things stand:
o The apache-{1.3,2.0}/htdocs and apache-devsite/apidoc trees have
been tagged with apache-docs-split-02
o The ,v files have been copied into top-level CVS modules as
httpd-docs-1.3/htdocs/
/apidoc/
httpd-docs-2.0/htdocs/
/apidoc/
o The access list for the httpd-docs-* modules has been updated;
everyone on the apache-{1.2,1.3,2.0} access list, plus at least
one docco volunteer, is on the list for these new locations
o Commit mail has been set up so that cvs commits to these new
locations should be sent to apache-docs@apache.org and
apache-{1.3,2.0}-cvs@apache.org
Things remaining to be done:
o cvs rm the htdocs and apidoc trees
o re-checkout the Locus sites from the new trees
o update the how-to-release document to include the instructions
on how to include the docco in the release (one more tag and one
more export command)
These not being done won't stand in the way of a roll right now;
I can just wipe out the new trees and re-create them. But if
we're not going to roll until sometime next week at the earliest,
I'll finish these up first.
I'm not sure this week-end is a good time to roll 1.3.13 in any
event; I'm pretty confident of the RemoveEncoding patch, but
there were some other changes in the last couple of days -- and
I suspect a bunch of us are going to be at the O'Reilly conference
next week. :-)
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: Web server docs proposal (take n)
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
"William A. Rowe, Jr." wrote:
>
> Contrawise, don't the apache-x source committers need to watch the
> docco commits so that we catch anything that was misinterpreted
> (or maybe learn something from the documentor's observations of
> other ways to rope that calf :?)
Sorry, missed this Q. Commits to the docco will be sent to the
source cvs list as well, so this is handled.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
RE: Web server docs proposal (take n)
Posted by "William A. Rowe, Jr." <wr...@lnd.com>.
> From: Rodent of Unusual Size [mailto:Ken.Coar@Golux.Com]
> Sent: Monday, May 29, 2000 10:37 AM
>
> Okey, here's another attempt, now that I have some time to write
> it up.
>
> What:
> I propose to create new CVS modules on the Apache system,
> and move the existing server documentation into them and out
> from under the source modules.
>
> Concerns and other items:
> o Why separate modules rather than finding a way to let these
> docco-only people work only in the htdocs/ subtree? Because of
> the mailing list issue, because this is how we've historically
> managed disjoint committer lists, because this is how other
> ASF projects seem to be handling subprojects, and because this
> doesn't require futzing with the CVS scripts that affect *all*
> of the ASF projects.
I have a simple question on this last item. For docco folks to be
effective, don't they need to at least watch the comments to the cvs
source list so they catch 'things that need new documentation'?
Contrawise, don't the apache-x source committers need to watch the
docco commits so that we catch anything that was misinterpreted
(or maybe learn something from the documentor's observations of
other ways to rope that calf :?)
I'm just not clear why two lists matter 'all that much', although it
may be easier to catch the 'doc' vs. 'src' changes (since I throw
trees into different folders myself so I can catch up on one version's
changes at a time. I'm avoiding catching up on the 45 2.0 tree commits
right now since I'm not of that mind at the moment - but the 1.3 commits
I have reviewed and they look great :)
It's my last remaining concern, I'm still +1 for the split. Does it
matter, however, if this holds up the release or happens immediately
afterwards, since it shouldn't affect the 1.3.13 distribution? If you
are already all set, then just let it fly, of course :)
Bill
Re: Web server docs proposal (take n)
Posted by rb...@covalent.net.
> > When the new module is created I would like to see all current
> > apache-cvs subscribers added to the new list. I don't expect so
> > much traffic that this will be a real issue, and it is a subtle
> > reminder that we are all responsible for docs. :-)
>
> The update mailing list for the new modules, as proposed, is
> comprised of the existing apache-cvs list and apache-docs list.
> Probably just a .qmail file forwarding to both.
Cool, I missed that part when I read the proposal. :-)
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Web server docs proposal (take n)
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
rbb@covalent.net wrote:
>
> When the new module is created I would like to see all current
> apache-cvs subscribers added to the new list. I don't expect so
> much traffic that this will be a real issue, and it is a subtle
> reminder that we are all responsible for docs. :-)
The update mailing list for the new modules, as proposed, is
comprised of the existing apache-cvs list and apache-docs list.
Probably just a .qmail file forwarding to both.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: Web server docs proposal (take n)
Posted by rb...@covalent.net.
On Mon, 29 May 2000, Rodent of Unusual Size wrote:
> Okey, here's another attempt, now that I have some time to write
> it up.
+1
> Concerns and other items:
When the new module is created I would like to see all current apache-cvs
subscribers added to the new list. I don't expect so much traffic that
this will be a real issue, and it is a subtle reminder that we are all
responsible for docs. :-)
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Web server docs proposal (take n)
Posted by rb...@covalent.net.
On Mon, 29 May 2000, Rodent of Unusual Size wrote:
> Okey, here's another attempt, now that I have some time to write
> it up.
+1
> Concerns and other items:
When the new module is created I would like to see all current apache-cvs
subscribers added to the new list. I don't expect so much traffic that
this will be a real issue, and it is a subtle reminder that we are all
responsible for docs. :-)
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Web server docs proposal (take n)
Posted by Marc Slemko <ma...@znep.com>.
On Tue, 30 May 2000, Greg Stein wrote:
> On Tue, 30 May 2000, Marc Slemko wrote:
> > On Mon, 29 May 2000, Rodent of Unusual Size wrote:
> >...
> > > o Why separate modules rather than finding a way to let these
> > > docco-only people work only in the htdocs/ subtree? Because of
> > > the mailing list issue, because this is how we've historically
> > > managed disjoint committer lists, because this is how other
> > > ASF projects seem to be handling subprojects, and because this
> > > doesn't require futzing with the CVS scripts that affect *all*
> > > of the ASF projects.
> >
> > Your use of the word "module" is very confusing. A "module", as
>
> He means /home/cvs/httpd-docs-1.3/ and /home/cvs/httpd-docs-2.0/
I know what he means. However, he is trying to suggest that somehow
that is a "module" and is specical to CVS. That is not what a CVS
module is. The world module has a very specific meaning.
>
> > defined by CVS, is either an entry in the modules file or a particular
> > path to the root of a tree of files. So the docs are already their
> > own module. And you can add an entry to the modules file just fine
> > so you can do a "cvs checkout httpd-docs-1.3" and get apache-1.3/htdocs.
> > So there is no change required to put the docs in their own module.
> > They are there.
> >
> > There is nothing required to allow other people to commit to only the
> > htdocs subdirectory other than adding them all to a group and chgrping
> > that subdirectory.
> >
> > The mailing list issues aren't too had to handle, especially if you
> > subscribe to the idea that if docs and code change in one commit, then
> > they should be mailed together because they are related. Then you just
> > need a tiny little filter getting mail to the main CVS commit list and
> > forwarding anything that includes docs changes to the random other docs
> > only list.
>
> Ken is operating from a known standpoint: create new top-level modules.
> All this mucking around could create problems within the repository. For
> example, consider the case where an "httpd" cvs user commits to
> apache-1.3/htdocs/ and it changes the group setting. Oops! Now the docs
> people cannot change that.
> (dunno if FreeBSD has a "sticky group" bit like Linux)
That is how it already has to work! There is nothing that tells
CVS to magically use a certain group for a certain subdirectory as
things are now; CVS knows nothing about the OS groups. The OS does
it. There is nothing different between having cvsroot/foo and
cvsroot/bar and having cvsroot/foo and cvsroot/foo/bar as far as
how groups work.
Once you understand how CVS is doing things anyway, it really isn't
a matter of any "mucking around". The only "mucking around" is with
some locally hacked up scripts to change how they mail stuff, or
just leave that out entirely and use a procmail filter or something.
>
> -1 on trying to create new operational modes like Marc suggests. I've
> previously stated +1 on Ken's approach.
It isn't a "new operational mode" once you understand how CVS works anyway.
>
> > Are you certain that commits that commit to both top level directories at
> > once will be mailed out properly anyway?
>
> Nobody does that today, so it is not a requirement for tomorrow. If it
> works, then great. Otherwise, it just doesn't matter.
One of the things stated earlier was that people who want to can
just check the docs tree out in a htdocs subdirectory of their
working directory, and act like it was never changed. Committers
should be committing docs changes to go along with their code at
the same time they do the code. If they do that, then they will
try to commit to two "top level modules" at once. cvs may separate
the commits enough by itself to avoid this problem. I don't know.
If it doesn't, then you will end up with the log being sent to the
list as defined by the first file being committed. And that isn't
very good.
It _IS_ a requirement for tomorrow because we are now taking two trees
that are intrinsically related and pulling them apart, then saying that if
people want them together they can do it themself. The consequences of
doing that have to be considered. I do not consider it to be a good
tradeoff to require committers who are committing code and docs changes to
have to go to two separate places and do two separate commits, etc. That
is the completely wrong direction.
Re: Web server docs proposal (take n)
Posted by Marc Slemko <ma...@znep.com>.
On Tue, 30 May 2000, Greg Stein wrote:
> On Tue, 30 May 2000, Marc Slemko wrote:
> > On Mon, 29 May 2000, Rodent of Unusual Size wrote:
> >...
> > > o Why separate modules rather than finding a way to let these
> > > docco-only people work only in the htdocs/ subtree? Because of
> > > the mailing list issue, because this is how we've historically
> > > managed disjoint committer lists, because this is how other
> > > ASF projects seem to be handling subprojects, and because this
> > > doesn't require futzing with the CVS scripts that affect *all*
> > > of the ASF projects.
> >
> > Your use of the word "module" is very confusing. A "module", as
>
> He means /home/cvs/httpd-docs-1.3/ and /home/cvs/httpd-docs-2.0/
I know what he means. However, he is trying to suggest that somehow
that is a "module" and is specical to CVS. That is not what a CVS
module is. The world module has a very specific meaning.
>
> > defined by CVS, is either an entry in the modules file or a particular
> > path to the root of a tree of files. So the docs are already their
> > own module. And you can add an entry to the modules file just fine
> > so you can do a "cvs checkout httpd-docs-1.3" and get apache-1.3/htdocs.
> > So there is no change required to put the docs in their own module.
> > They are there.
> >
> > There is nothing required to allow other people to commit to only the
> > htdocs subdirectory other than adding them all to a group and chgrping
> > that subdirectory.
> >
> > The mailing list issues aren't too had to handle, especially if you
> > subscribe to the idea that if docs and code change in one commit, then
> > they should be mailed together because they are related. Then you just
> > need a tiny little filter getting mail to the main CVS commit list and
> > forwarding anything that includes docs changes to the random other docs
> > only list.
>
> Ken is operating from a known standpoint: create new top-level modules.
> All this mucking around could create problems within the repository. For
> example, consider the case where an "httpd" cvs user commits to
> apache-1.3/htdocs/ and it changes the group setting. Oops! Now the docs
> people cannot change that.
> (dunno if FreeBSD has a "sticky group" bit like Linux)
That is how it already has to work! There is nothing that tells
CVS to magically use a certain group for a certain subdirectory as
things are now; CVS knows nothing about the OS groups. The OS does
it. There is nothing different between having cvsroot/foo and
cvsroot/bar and having cvsroot/foo and cvsroot/foo/bar as far as
how groups work.
Once you understand how CVS is doing things anyway, it really isn't
a matter of any "mucking around". The only "mucking around" is with
some locally hacked up scripts to change how they mail stuff, or
just leave that out entirely and use a procmail filter or something.
>
> -1 on trying to create new operational modes like Marc suggests. I've
> previously stated +1 on Ken's approach.
It isn't a "new operational mode" once you understand how CVS works anyway.
>
> > Are you certain that commits that commit to both top level directories at
> > once will be mailed out properly anyway?
>
> Nobody does that today, so it is not a requirement for tomorrow. If it
> works, then great. Otherwise, it just doesn't matter.
One of the things stated earlier was that people who want to can
just check the docs tree out in a htdocs subdirectory of their
working directory, and act like it was never changed. Committers
should be committing docs changes to go along with their code at
the same time they do the code. If they do that, then they will
try to commit to two "top level modules" at once. cvs may separate
the commits enough by itself to avoid this problem. I don't know.
If it doesn't, then you will end up with the log being sent to the
list as defined by the first file being committed. And that isn't
very good.
It _IS_ a requirement for tomorrow because we are now taking two trees
that are intrinsically related and pulling them apart, then saying that if
people want them together they can do it themself. The consequences of
doing that have to be considered. I do not consider it to be a good
tradeoff to require committers who are committing code and docs changes to
have to go to two separate places and do two separate commits, etc. That
is the completely wrong direction.
Re: Web server docs proposal (take n)
Posted by Greg Stein <gs...@lyra.org>.
On Tue, 30 May 2000, Marc Slemko wrote:
> On Mon, 29 May 2000, Rodent of Unusual Size wrote:
>...
> > o Why separate modules rather than finding a way to let these
> > docco-only people work only in the htdocs/ subtree? Because of
> > the mailing list issue, because this is how we've historically
> > managed disjoint committer lists, because this is how other
> > ASF projects seem to be handling subprojects, and because this
> > doesn't require futzing with the CVS scripts that affect *all*
> > of the ASF projects.
>
> Your use of the word "module" is very confusing. A "module", as
He means /home/cvs/httpd-docs-1.3/ and /home/cvs/httpd-docs-2.0/
> defined by CVS, is either an entry in the modules file or a particular
> path to the root of a tree of files. So the docs are already their
> own module. And you can add an entry to the modules file just fine
> so you can do a "cvs checkout httpd-docs-1.3" and get apache-1.3/htdocs.
> So there is no change required to put the docs in their own module.
> They are there.
>
> There is nothing required to allow other people to commit to only the
> htdocs subdirectory other than adding them all to a group and chgrping
> that subdirectory.
>
> The mailing list issues aren't too had to handle, especially if you
> subscribe to the idea that if docs and code change in one commit, then
> they should be mailed together because they are related. Then you just
> need a tiny little filter getting mail to the main CVS commit list and
> forwarding anything that includes docs changes to the random other docs
> only list.
Ken is operating from a known standpoint: create new top-level modules.
All this mucking around could create problems within the repository. For
example, consider the case where an "httpd" cvs user commits to
apache-1.3/htdocs/ and it changes the group setting. Oops! Now the docs
people cannot change that.
(dunno if FreeBSD has a "sticky group" bit like Linux)
-1 on trying to create new operational modes like Marc suggests. I've
previously stated +1 on Ken's approach.
> Are you certain that commits that commit to both top level directories at
> once will be mailed out properly anyway?
Nobody does that today, so it is not a requirement for tomorrow. If it
works, then great. Otherwise, it just doesn't matter.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
Re: Web server docs proposal (take n)
Posted by Greg Stein <gs...@lyra.org>.
On Tue, 30 May 2000, Marc Slemko wrote:
> On Mon, 29 May 2000, Rodent of Unusual Size wrote:
>...
> > o Why separate modules rather than finding a way to let these
> > docco-only people work only in the htdocs/ subtree? Because of
> > the mailing list issue, because this is how we've historically
> > managed disjoint committer lists, because this is how other
> > ASF projects seem to be handling subprojects, and because this
> > doesn't require futzing with the CVS scripts that affect *all*
> > of the ASF projects.
>
> Your use of the word "module" is very confusing. A "module", as
He means /home/cvs/httpd-docs-1.3/ and /home/cvs/httpd-docs-2.0/
> defined by CVS, is either an entry in the modules file or a particular
> path to the root of a tree of files. So the docs are already their
> own module. And you can add an entry to the modules file just fine
> so you can do a "cvs checkout httpd-docs-1.3" and get apache-1.3/htdocs.
> So there is no change required to put the docs in their own module.
> They are there.
>
> There is nothing required to allow other people to commit to only the
> htdocs subdirectory other than adding them all to a group and chgrping
> that subdirectory.
>
> The mailing list issues aren't too had to handle, especially if you
> subscribe to the idea that if docs and code change in one commit, then
> they should be mailed together because they are related. Then you just
> need a tiny little filter getting mail to the main CVS commit list and
> forwarding anything that includes docs changes to the random other docs
> only list.
Ken is operating from a known standpoint: create new top-level modules.
All this mucking around could create problems within the repository. For
example, consider the case where an "httpd" cvs user commits to
apache-1.3/htdocs/ and it changes the group setting. Oops! Now the docs
people cannot change that.
(dunno if FreeBSD has a "sticky group" bit like Linux)
-1 on trying to create new operational modes like Marc suggests. I've
previously stated +1 on Ken's approach.
> Are you certain that commits that commit to both top level directories at
> once will be mailed out properly anyway?
Nobody does that today, so it is not a requirement for tomorrow. If it
works, then great. Otherwise, it just doesn't matter.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
Re: Web server docs proposal (take n)
Posted by Marc Slemko <ma...@znep.com>.
On Mon, 29 May 2000, Rodent of Unusual Size wrote:
> Why:
> Because we have lots of people who are interested in contributing
> to the Web server project by working on the docs rather than the
> code. This includes people who want to provide translations for
> various of the pages. Currently the only way they can do this is
> by submitting a patch to the development mailing list, with no
> assurance that it won't get ignored. Putting the documentation
> into a separate module means we can have a separate -- and less
> restrictive, perhaps -- list of people who can commit to the
> documentation project.
Ok, so the reason is to allow a different set of committers to the docs,
period. No other reason. Right? I can agree with that desire.
> o Why separate modules rather than finding a way to let these
> docco-only people work only in the htdocs/ subtree? Because of
> the mailing list issue, because this is how we've historically
> managed disjoint committer lists, because this is how other
> ASF projects seem to be handling subprojects, and because this
> doesn't require futzing with the CVS scripts that affect *all*
> of the ASF projects.
Your use of the word "module" is very confusing. A "module", as
defined by CVS, is either an entry in the modules file or a particular
path to the root of a tree of files. So the docs are already their
own module. And you can add an entry to the modules file just fine
so you can do a "cvs checkout httpd-docs-1.3" and get apache-1.3/htdocs.
So there is no change required to put the docs in their own module.
They are there.
There is nothing required to allow other people to commit to only the
htdocs subdirectory other than adding them all to a group and chgrping
that subdirectory.
The mailing list issues aren't too had to handle, especially if you
subscribe to the idea that if docs and code change in one commit, then
they should be mailed together because they are related. Then you just
need a tiny little filter getting mail to the main CVS commit list and
forwarding anything that includes docs changes to the random other docs
only list.
Are you certain that commits that commit to both top level directories at
once will be mailed out properly anyway?
But, whatever. If you are insistent on going ahead regardless... so be
it.
Re: Web server docs proposal (take n)
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Greg Stein wrote:
>
> Copied. They must continue to exist in the old locations so that
> we can rebuild releases based on previous tags.
Um, when I said 'moved' I meant 'copied and cvs rm'd'. Which
preserves the rebuildability. What I was getting at was
whether the appearance in the new location and the absence
in the old should be atomic or not.
Re: Web server docs proposal (take n)
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Greg Stein wrote:
>
> Copied. They must continue to exist in the old locations so that
> we can rebuild releases based on previous tags.
Um, when I said 'moved' I meant 'copied and cvs rm'd'. Which
preserves the rebuildability. What I was getting at was
whether the appearance in the new location and the absence
in the old should be atomic or not.
>From the rest of your message, it sounds as though you would prefer
the change to be atomic.
I expect the files to be copied directly in the repository in
order to retain the history.
--
#ken P-)}
Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>
Re: Web server docs proposal (take n)
Posted by Greg Stein <gs...@lyra.org>.
On Mon, 29 May 2000, Rodent of Unusual Size wrote:
>...
> What:
> I propose to create new CVS modules on the Apache system,
> and move the existing server documentation into them and out
> from under the source modules.
+1
>...
> How:
> I propose that two new modules, httpd-docs-1.3 and httpd-docs-2.0,
> be created. The current src/htdocs/ directory trees in the apache-1.3
> and apache-2.0 CVS modules, and the apidoc/ tree in the apache-devsite
> module, would be tagged, and then the files in those trees either
> copied or moved to the appropriate httpd-docs-* tree.
Copied. They must continue to exist in the old locations so that we can
rebuild releases based on previous tags.
Personally, I'd "cvs add" copies of the HEAD of these areas, with a
checkin comment pointing to their old location. But if the choice is going
to be copy or move... take copy.
> I suggest
> that the address to which CVS updates are sent should include both
> the apache-docs list and the apache-cvs list,
+1
>...
> At some point the htdocs/ subtrees would be removed from the
> source trees. That can either be immediate or happen sometime
"cvs delete" immediately.
They can't be physically deleted because of the "build old release" issue.
And since they are not physically deleted, then we can always recover in
case something truly does go wrong.
I suggest immediately so that we don't get commits to the wrong location.
>...
> o Why two modules rather than one with branches? For simplicity and
> for parity with the source trees whose contents they track.
+1
> o Why the "httpd-" module names instead of "apache-"? Because
> 'Apache' now means a lot more than just the Web server project,
> and 'httpd' has been selected as the name of that project itself.
> Whether the existing 'apache-*' modules will get renamed to
> 'httpd-*', or will remain with their current legacy names, is
> a separate issue -- but new modules should, I think, follow the
> now-current naming conventions.
+1
> o Why separate modules rather than finding a way to let these
> docco-only people work only in the htdocs/ subtree? Because of
> the mailing list issue, because this is how we've historically
> managed disjoint committer lists, because this is how other
> ASF projects seem to be handling subprojects, and because this
> doesn't require futzing with the CVS scripts that affect *all*
> of the ASF projects.
+1
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
Re: Web server docs proposal (take n)
Posted by Marc Slemko <ma...@znep.com>.
On Mon, 29 May 2000, Rodent of Unusual Size wrote:
> Why:
> Because we have lots of people who are interested in contributing
> to the Web server project by working on the docs rather than the
> code. This includes people who want to provide translations for
> various of the pages. Currently the only way they can do this is
> by submitting a patch to the development mailing list, with no
> assurance that it won't get ignored. Putting the documentation
> into a separate module means we can have a separate -- and less
> restrictive, perhaps -- list of people who can commit to the
> documentation project.
Ok, so the reason is to allow a different set of committers to the docs,
period. No other reason. Right? I can agree with that desire.
> o Why separate modules rather than finding a way to let these
> docco-only people work only in the htdocs/ subtree? Because of
> the mailing list issue, because this is how we've historically
> managed disjoint committer lists, because this is how other
> ASF projects seem to be handling subprojects, and because this
> doesn't require futzing with the CVS scripts that affect *all*
> of the ASF projects.
Your use of the word "module" is very confusing. A "module", as
defined by CVS, is either an entry in the modules file or a particular
path to the root of a tree of files. So the docs are already their
own module. And you can add an entry to the modules file just fine
so you can do a "cvs checkout httpd-docs-1.3" and get apache-1.3/htdocs.
So there is no change required to put the docs in their own module.
They are there.
There is nothing required to allow other people to commit to only the
htdocs subdirectory other than adding them all to a group and chgrping
that subdirectory.
The mailing list issues aren't too had to handle, especially if you
subscribe to the idea that if docs and code change in one commit, then
they should be mailed together because they are related. Then you just
need a tiny little filter getting mail to the main CVS commit list and
forwarding anything that includes docs changes to the random other docs
only list.
Are you certain that commits that commit to both top level directories at
once will be mailed out properly anyway?
But, whatever. If you are insistent on going ahead regardless... so be
it.
Re: Web server docs proposal (take n)
Posted by Greg Stein <gs...@lyra.org>.
On Mon, 29 May 2000, Rodent of Unusual Size wrote:
>...
> What:
> I propose to create new CVS modules on the Apache system,
> and move the existing server documentation into them and out
> from under the source modules.
+1
>...
> How:
> I propose that two new modules, httpd-docs-1.3 and httpd-docs-2.0,
> be created. The current src/htdocs/ directory trees in the apache-1.3
> and apache-2.0 CVS modules, and the apidoc/ tree in the apache-devsite
> module, would be tagged, and then the files in those trees either
> copied or moved to the appropriate httpd-docs-* tree.
Copied. They must continue to exist in the old locations so that we can
rebuild releases based on previous tags.
Personally, I'd "cvs add" copies of the HEAD of these areas, with a
checkin comment pointing to their old location. But if the choice is going
to be copy or move... take copy.
> I suggest
> that the address to which CVS updates are sent should include both
> the apache-docs list and the apache-cvs list,
+1
>...
> At some point the htdocs/ subtrees would be removed from the
> source trees. That can either be immediate or happen sometime
"cvs delete" immediately.
They can't be physically deleted because of the "build old release" issue.
And since they are not physically deleted, then we can always recover in
case something truly does go wrong.
I suggest immediately so that we don't get commits to the wrong location.
>...
> o Why two modules rather than one with branches? For simplicity and
> for parity with the source trees whose contents they track.
+1
> o Why the "httpd-" module names instead of "apache-"? Because
> 'Apache' now means a lot more than just the Web server project,
> and 'httpd' has been selected as the name of that project itself.
> Whether the existing 'apache-*' modules will get renamed to
> 'httpd-*', or will remain with their current legacy names, is
> a separate issue -- but new modules should, I think, follow the
> now-current naming conventions.
+1
> o Why separate modules rather than finding a way to let these
> docco-only people work only in the htdocs/ subtree? Because of
> the mailing list issue, because this is how we've historically
> managed disjoint committer lists, because this is how other
> ASF projects seem to be handling subprojects, and because this
> doesn't require futzing with the CVS scripts that affect *all*
> of the ASF projects.
+1
Cheers,
-g
--
Greg Stein, http://www.lyra.org/