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/>
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/>