Mailing-List: contact new-httpd-help@apache.org; run by ezmlm
Precedence: bulk
Reply-To: new-httpd@apache.org
Date: Fri, 21 Apr 2000 08:56:27 -0600 (MDT)
From: Marc Slemko <marcs@znep.com>
To: new-httpd@apache.org
Subject: Re: httpd-docs CVS modules
In-Reply-To: <38FDF07D.904C4121@Golux.Com>
Message-ID: <Pine.BSF.4.20.0004210809260.511-100000@alive.znep.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII

On Wed, 19 Apr 2000, Rodent of Unusual Size wrote:

> Marc Slemko wrote:
> > 
> > On Wed, 19 Apr 2000, Rodent of Unusual Size wrote:
> > 
> > > Why:
> > >
> > > 1. Because we've got a lot of volunteers interested in working
> > >    specifically on the documentation, not on the code; in addition
> > >    to fixers and doc-writers, we've got a number of people
> > >    eager/willing to translate the actual documentation into other
> > >    languages
> > > 2. With the docs in separate modules, we can different (looser)
> > >    commit lists
> > 
> > As I asked before, why can't you set things up so you can do that as
> > things are now?
> 
> AFAIK, because of the CVSROOT/avail process and the issues with

The avail file isn't anything more than an arbitrary file that is checked
by an arbitrary (cvs_acls.pl) bit of code that can do whatever it wants.

> group/user ownership and permissions at the Unix level.
> 
> In your message on this last September, you said:

Yea, I said that, and I never got a reply as far as I can find...

> > Why can't we just tell CVS that "user x, y, z has access to a module
> > named xxx-docs-1.3, defined to be apache-1.3/htdocs" then create a
> > group for that and make the docs directory writable by that group
> > instead of group cvs?
> 
> a. because the first time someone who has the wider CVS access
> adds something, it won't be owned by the docs group but by
> the code group.  Manual intervention by someone with root required.

So why doesn't that happen right now with people in multiple groups?

As far as CVS is concerned, take a look in the current "modules"
file.  Do you see any modules for java-*, xml-*, etc.?  Nope.  Why
are they working?  CVS doesn't know anything about these multiple
collections that are supposed to have different permissions.  Yet
they work and, if they didn't, then what you are suggesting wouldn't
work anyway.

The reason is because, on BSD systems, new files and directories 
automatically inherit the same group as their parent.  That behavior 
is relied on very heavily in the current setup.  Give it a try.  There
is nothing special about something being a second level directory
instead of a top level directory under CVSROOT.

> b. because our CVS procedures work on the basis of directory names,
> not module names.  But that's probably surmountable.

I'm not sure what "our CVS procedures" are, but certainly.

> 
> > > 3. "httpd-docs-v1" and "-v2" because of the mess we've had
> > >    with the docs in the past (like the 1.2/1.3/2.0 header/footer
> > >    confusion)
> > 
> > I'm not sure I understand.
> 
> People were looking at the HEAD docs for 1.3 and trying to apply
> them to their 1.2 software.  Breakage.  So we checked out the
> 1.2 branch into a separate tree, and modified the header/footer
> files to say "1.2".  Then we modified the HEAD header/footer files
> to say "1.3".  Then when we released 2.0a1 at Orlando, the docs
> said "1.3", so Brian removed the version from the header/footer
> files altogether.  It's messy.

Oh.  So you are proposing a lot more than just splitting out the docs
tree.  You are proposing that we never have any branches for docs within a
major version?  Ouch.

I don't understand how that solves the problem you talk about.  "people
were looking at the HEAD docs for 1.3 and trying to apply them to their
1.2 software".  So under your scheme anyone using a x.y version where y
wasn't the latest would just be out of luck?

So when there is a 2.1, then there will be no way to create and update the
docs as the code is written but before it is in a public release?

If there is confusion about what docs correspond to what version,
then that is a sign that it matters which ones correspond.  If they
didn't, then no one would care.  The solution isn't to get rid of
multiple versions, the solution is to manage them (well, more specifically,
their visibility to the world) better.

> > So you are saying that if we create an apache-2.1 module, then it
> > should still use httpd-docs-v2?
> 
> Yes.  See my answer below to your 'one for each code tree' question.
> 
> > And why is it "apache" vs. "httpd-docs"?
> 
> Why is *what* "apache"?  The code tree?  Go look at Brian's
> renaming proposal, and the other threads concerning bringing the
> HTTP server project names into alignment with the other projects.

I asked the same question and got essentially the same answer a
year ago...  that's all.  If it will really happen, great.  If
"httpd" is the direction to go in (which I support), great.  But
in the past when I suggested "httpd" for things instead of "apache"
people didn't like it.

Just making sure that is well understood and is the intent when using
"httpd".

> 
> > Why wouldn't there be a docs tree to mirror each code tree?
> 
> No particular reason, other than avoiding massive duplication
> since the docs don't change nearly as much as the code.  The
> description of a directive or API function changes at less than
> a tenth the pace of the code that actually implements it.

And by pulling the docs out, you are encouraging it to change even less
and stay up to date even less.

> > And why invent a new naming scheme when we have one already for
> > the code trees?
> 
> Um, what invention?  More to the point, what existing scheme?
> Go take a look at the list of modules; the only commonality
> amongst them is that each project has a "foo" and a "foo-site"
> module.

"foo-1.3"  
"foo-v1"

Where did the "v" come from?

> > So then 2.1 docs would be a branch in the v2 docs while 2.1
> > would probably (if tradition is followed) be a separate module?  
> > Sounds confusing to me.
> 
> Solved (at the cost of duplication) by having a 1:1 ration between
> docco and code trees.  That seems stupid to me, but I don't really
> care.  I originally proposed a single docs module; adding the
> version number to it was actually your idea.  A good one, IMHO.

I'm confused.  So would you expect there to be branches or not?  Your
earlier talk about what not having versions for each x.y tree implied
that you didn't want that at all.  

It doesn't make any sense to me to use branches for the docs in places
that different repositories are used in the code.

> 
> > > 4. With doc-fixers having direct access to the appropriate bits of
> > >    CVS, patches don't have to queue up (and get ignored for months)
> > >    in STATUS
> > 
> > This is reason 1 and 2 all over.
> 
> No, this is a separate reason: taking the onus and responsibilty
> of tracking crap about which they don't care off the coders who
> want to work on code.  Namely, the current commit list.

They all contribute to the exact same goal: allowing more open access
to the docs.  I have seen no other reasons presented.  And I don't 
see how moving them into their own module (well, there actually is
already a docs module...) helps that.

> > Can you give some examples of who?
> 
> Alexandre Dutriaux, LangBridge.Com (if we could get them to donate
> the effort rather than charge for it), at least two Polish-speaking
> people, Sayan Wolrd, Kevin Lo, Alberto Curro, possibly the people at
> apache.ru, ...  And that's just the people interested in translating
> the documentation, and doesn't include at least as many that would
> like to contribute improvements.

So it has already been decided that we want to have translations of the
docs and how we are going to support such translations given that 
they will always be at least one step behind the english docs?

Note that I have no objections to giving others access to the doc trees,
although I haven't seen all that much demand for it.  But if there 
is demand that I am not seeing, fine.  

> > And why is it necessary to split it into a separate module to do so?
> 
> You come up with a solution that RELIABLY allows some people to
> hack on *only* one portion of a module under our current CVS setup
> and I'll be glad to hear it.  Unfortunately, I don't see one.

$ for user in `users in httpd group`; do add user to httpd-docs group; done
$ chgrp -R httpd-docs $CVSROOT/apache-?.?/htdocs

> So unless there's one I'm not seeing, it's either change our
> CVS procedures or create a new module.  Sorry, I think the latter
> is by far the safer and lower-impact route..
> 
> Turn it around, please, and answer: why *shouldn't* it be a separate
> module?

Because it invites a greater separation between the docs and code.
People should, whenever possible, make appropriate changes to docs
whenever any code is committed.  The docs are not this separate entity
that exists independent of the code.  They need the same version control,
etc. that the code does.

The very fact that you are suggesting that we don't need a docs tree 
for each dev tree shows one of the reasons why pulling them out of the
code tree is a bad idea.

> 
> > > Since this was discussed earlier, this message is sort of a
> > > pro forma 'heads up!' to warn of the change, and to give people
> > > a last chance to stop/change/improve the process.
> > 
> > The above details were _not_ discussed, and as I recall it certainly
> > wasn't a overwhelming "go for it".  As I recall, I asked the same
> > questions before but don't recall getting any answers...
> 
> Well, you got answers then, and you've got them (again) now.

I'm afraid that the only reply I can see to the message of mine that 
you quote above just ignored my question about why it is necessary...

> 
> Perhaps not an overwhelming 'go for it,' but Brian, Dirk, Jim, Ryan,
> Ben, Randy, and I were quite in favour, Ralf seemed amenable, and
> you were the only one with questions.

You can't use support for something a year ago as a prerogative to go ahead
and so something somewhat similar (but different) now without proper
discussion...

> 
> Given that list of support, unless you veto I'm still planning to
> go ahead.  (Or if those people change their minds. :-)

-1

If you can give a good reason why you need to move them to their own 
top level directory under CVSROOT, fine.  But I haven't seen any reason.
And I do not understand what you are proposing WRT dealing with docs
trees for each separate x.y version.