incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Niall Pemberton <>
Subject Re: How documentation != code, and how to "do" policy (was: Re: Publishing api docs for Subversion)
Date Mon, 07 Dec 2009 19:35:15 GMT
On Mon, Dec 7, 2009 at 7:03 PM, Doug Cutting <> wrote:
> Leo Simons wrote:
>> So, subversion publishes their trunk API docs nightly, for the
>> convenience of their own developers and the surrounding tool developer
>> community. All those people mostly want trunk API docs, and they want
>> them mostly so they don't have to run doxygen themselves. There's
>> really no need to protect the normal users of the subversion website
>> from "bad" API docs, they won't be using those docs at all.
> It's fine to make nightly builds available, including of documentation.  All
> I'm suggesting is that, just as nightly builds should not be linked to from
> the general download page, nightly documentation should not be linked to
> from the general documentation page.  Both, like links to ViewVC, should
> only be linked to from developer-specific pages.
>> The best response in this case is probably to look for a similar
>> project around the ASF that has already figured out a similar process
>> and see if things are compatible. Like, httpd or apr. Ah, they do the
>> same. Cool, done.
> Just because HTTPD or any other project does something does not always mean
> it's best practice.  It often does, but, in this case, I think adding "dev"
> to a link in the sidebar is a poor substitute for moving this link to
>> If you have an idea about what the policy is, check your idea against
>> the extensive docs on and If
>> your idea is in there, point people at the documented policy.
> I believe I cited this earlier in the thread:
> "Do not include any links on the project website that might encourage
> non-developers to download and use nightly builds, snapshots, release
> candidates, or any other similar package."
> This is motivated by legal reasons.  Copyright and license issues are
> possible for documentation as well as code, so I see no reason to make an
> exception for nightly documentation builds.
>> Always remember the incubator is not here to invent policy and apply
>> it to incubating projects. The incubator is here to help incubating
>> projects navigate the ASF so they can create and distribute software
>> "ASF style".
> I'm not inventing policy.  I'm describing the way every project I'm involved
> with operates and interpreting the rules posted at

You're representing something as policy that is not. You're taking a
policy that applies to release artifacts and stretching it to
something it wasn't intended to cover. In the absence of specific
policy then *objections* are out of order since its up to the PMC of a
project to decide these things. We also have a responsibility here to
not make incubating projects cry and weep and wonder why they ever
wanted to join the ASF - which threads like this over where to put a
link on their site must surely do.


> Doug

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message