You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@incubator.apache.org by Bhuvaneswaran A <bh...@apache.org> on 2009/12/02 18:48:01 UTC
Publishing api docs for Subversion
Here's a query related to publishing api docs for Subversion project
periodically.
We tend to update the api docs generated using doxygen and java doc on
a nightly basis. We are evaluating a workaround to publish it
periodically. Based on investigation I did so far, most of projects
namely apr, hadoop, jakarta seem to place the apidocs in site/ area,
not updated periodically though. As our use case is to update
periodically, we wouldn't want to commit the auto generated docs in
asf repository often.
Considering these aspects, here's what we are planning to do:
Setup a Hudson job in hudson.zones.apache.org farm that would generate
the documentation using doxygen and javadoc. This can be setup to run
periodically, may be once a day or once a week. Then, push the
documentation files to people.apache.org into one of our accounts
using SCP plugin that is already available in Hudson. We may use a
passphrase/keyfile for authentication.
Please shed some light if this is not the right approach, and/or if
you could suggest a better/alternate approach, that would be helpful.
--
Regards,
Bhuvaneswaran A
www.livecipher.com
GPG: 0x7A13E5B0
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Bernd Fondermann <be...@googlemail.com>.
On Wed, Dec 2, 2009 at 18:48, Bhuvaneswaran A <bh...@apache.org> wrote:
> Here's a query related to publishing api docs for Subversion project
> periodically.
>
> We tend to update the api docs generated using doxygen and java doc on
> a nightly basis. We are evaluating a workaround to publish it
> periodically. Based on investigation I did so far, most of projects
> namely apr, hadoop, jakarta seem to place the apidocs in site/ area,
> not updated periodically though. As our use case is to update
> periodically, we wouldn't want to commit the auto generated docs in
> asf repository often.
>
> Considering these aspects, here's what we are planning to do:
> Setup a Hudson job in hudson.zones.apache.org farm that would generate
> the documentation using doxygen and javadoc. This can be setup to run
> periodically, may be once a day or once a week. Then, push the
> documentation files to people.apache.org into one of our accounts
> using SCP plugin that is already available in Hudson. We may use a
> passphrase/keyfile for authentication.
>
> Please shed some light if this is not the right approach, and/or if
> you could suggest a better/alternate approach, that would be helpful.
>
> --
> Regards,
> Bhuvaneswaran A
> www.livecipher.com
> GPG: 0x7A13E5B0
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Bhuvaneswaran A <bh...@gmail.com>.
On Fri, Dec 4, 2009 at 2:12 PM, Jukka Zitting <ju...@gmail.com> wrote:
> Some Apache projects are now using Hudson builds to generate their web
> sites from sources stored in svn. The generated site is periodically
> rsynced to the correct place people.apache.org. This setup is still a
> bit experimental but should cover your needs pretty well.
Thanks for sharing your views, Jukka.
Thinking deeper into this task, the Hudson has a inbuilt feature to
publish html content if placed in userContent folder. The javadoc
publishing capability is already present in Hudson. Taking advantage
of both these Hudson features, I'm thinking a) configure the job(s) to
generate doxygen and javadoc documentation. b) create a link to this
document to userContent. With this setup, the documentation can be
made available here:
doxygen: http://hudson.zones.apache.org/hudson/userContent/subversion/doxygen/index.html
javadoc: http://hudson.zones.apache.org/hudson/userContent/subversion/javadoc/index.html
We may configure this job to run on daily basis.
AFAIK, in the past we did not publish doxygen/javadoc for stable
releases in Subversion project. If we had to so, we may place them in
svn under site/ directory corresponding to that release. The
documentation for trunk aka. on going changes can be made available in
the above url which we may link it from our home page, if need be.
To publish document in this fashion, all we need to do is create
Hudson job(s) appropriately. I'll propose this plan to our project
team and do the setup accordingly.
Thank you!
--
Regards,
Bhuvaneswaran A
www.livecipher.com
GPG: 0x7A13E5B0
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Jukka Zitting <ju...@gmail.com>.
Hi,
On Fri, Dec 4, 2009 at 4:18 AM, Bhuvaneswaran A <bh...@gmail.com> wrote:
> On Fri, Dec 4, 2009 at 4:23 AM, Hyrum K. Wright
> <hy...@mail.utexas.edu> wrote:
>> Back the original question: What's the best/typical way of generating
>> and providing these documents? Subversion is using svnwcsub to
>> publish subvesion.apache.org, but I don't think it's reasonable to check
>> in a copy of the API documentation.
>
> To add to it and if i was not clear in my original email, when I say
> "update docs on nightly basis", I mean updating the files every night.
> It does not mean generating new set of doc files every night.
Some Apache projects are now using Hudson builds to generate their web
sites from sources stored in svn. The generated site is periodically
rsynced to the correct place people.apache.org. This setup is still a
bit experimental but should cover your needs pretty well.
The infra@ and site-dev@ archives are not public so I unfortunately
can't point you to the relevant threads there, but see for example
http://markmail.org/message/6m5jwauk77krla5k for a related description
of how the Apache Tika web site is currently handled.
Please join the site-dev@ mailing list for more details and ideas on
how to improve the setup.
BR,
Jukka Zitting
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Bhuvaneswaran A <bh...@gmail.com>.
On Fri, Dec 4, 2009 at 4:23 AM, Hyrum K. Wright
<hy...@mail.utexas.edu> wrote:
>
> On Dec 3, 2009, at 2:14 PM, Paul Querna wrote:
>
>> On Thu, Dec 3, 2009 at 9:31 AM, Doug Cutting <cu...@apache.org> wrote:
>>> Paul Querna wrote:
>>>>
>>>> httpd and apr have published doxygen of their trunks periodically,
>>>> they aren't based on any release.
>>>
>>> Were these published these on the official public website or in the dev/
>>> section?
>>>
>>> I was under the impression that released documentation should be treated
>>> similarly to released code. The convention I've used is that stuff that's
>>> in trunk, stuff that's intended to be included in releases, is only
>>> published after release. Other pages on the website that are not included
>>> in releases, e.g., the project's home page, are clearly published without a
>>> release vote.
>>
>> <http://httpd.apache.org/docs/trunk/>
>>
>> Which is linked from the sidebar everywhere, and on the docs page:
>> <http://httpd.apache.org/docs/>
>
> Back the original question: What's the best/typical way of generating and providing these documents? Subversion is using svnwcsub to publish subvesion.apache.org, but I don't think it's reasonable to check in a copy of the API documentation.
To add to it and if i was not clear in my original email, when I say
"update docs on nightly basis", I mean updating the files every night.
It does not mean generating new set of doc files every night. Overall
we'll maintain just one copy that is updated every night. I wish there
should be a place other that site/ area in repository, if
people.apache.org is not apt.
--
Regards,
Bhuvaneswaran A
www.livecipher.com
GPG: 0x7A13E5B0
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by "Hyrum K. Wright" <hy...@mail.utexas.edu>.
On Dec 3, 2009, at 2:14 PM, Paul Querna wrote:
> On Thu, Dec 3, 2009 at 9:31 AM, Doug Cutting <cu...@apache.org> wrote:
>> Paul Querna wrote:
>>>
>>> httpd and apr have published doxygen of their trunks periodically,
>>> they aren't based on any release.
>>
>> Were these published these on the official public website or in the dev/
>> section?
>>
>> I was under the impression that released documentation should be treated
>> similarly to released code. The convention I've used is that stuff that's
>> in trunk, stuff that's intended to be included in releases, is only
>> published after release. Other pages on the website that are not included
>> in releases, e.g., the project's home page, are clearly published without a
>> release vote.
>
> <http://httpd.apache.org/docs/trunk/>
>
> Which is linked from the sidebar everywhere, and on the docs page:
> <http://httpd.apache.org/docs/>
Back the original question: What's the best/typical way of generating and providing these documents? Subversion is using svnwcsub to publish subvesion.apache.org, but I don't think it's reasonable to check in a copy of the API documentation.
-Hyrum
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Joe Schaefer <jo...@yahoo.com>.
----- Original Message ----
> From: Doug Cutting <cu...@apache.org>
> To: general@incubator.apache.org
> Sent: Mon, December 7, 2009 6:24:18 PM
> Subject: Re: Publishing api docs for Subversion
>
> Joe Schaefer wrote:
> > Exactly. That's the key difference between a release and a website, we
> > can't take the release back.
>
> Good point. We don't mirror the website on 3rd party sites like we do releases,
> nor does HTTPD currently package pre-release docs as an archive that folks might
> download and install locally. So this is less risky than promoting complete
> nightly builds. But what if a project starts posting the nightly documentation
> as a tarball, so that folks can access it while offline?
Well presumably it'd be made available to devs, not end users. I don't
have a problem with that either, as long as the context is clear.
>
> So I still worry that it sets a bad precedent to permit publishing a significant
> subset of a nightly build on a public website. I as yet see no reason why it's
> a problem to link to it from the developer portion of the site, like links to
> subversion, except that developers might already be used to finding it on the
> primary site. Which is precisely why, when a new project asks how to post its
> nightly documentation, we should tell them the best practice is to confine
> pre-release stuff to the developer portion of the site. There they can post it
> as individual pages, archives, a big PDF or whatever. We can keep this line
> clear: if it's content destined for release but that hasn't been released, it
> should only be available from the developer portion of the site.
We currently allow wikis to be used as public websites, so really we'd
need to write down a separate policy governing website content instead of
attempting to extend the release policy to cover it. Mostly infra's position
is that as long as there is a clear audit trail between what's posted and
who created the content, and that the content is under ICLA, we're ok with it.
As far as it being a best practice to put build-related webpages under /dev,
that'd be fine with me personally, and I don't think the svn devs would have
a problem with that suggestion. It's outright telling them no that I think
is uncalled for, whether based on the release policy or not. There is
certainly prior practice by PMCs to the contrary (best practice
notwithstanding).
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Joe Schaefer wrote:
> Exactly. That's the key difference between a release and a website, we
> can't take the release back.
Good point. We don't mirror the website on 3rd party sites like we do
releases, nor does HTTPD currently package pre-release docs as an
archive that folks might download and install locally. So this is less
risky than promoting complete nightly builds. But what if a project
starts posting the nightly documentation as a tarball, so that folks can
access it while offline?
So I still worry that it sets a bad precedent to permit publishing a
significant subset of a nightly build on a public website. I as yet see
no reason why it's a problem to link to it from the developer portion of
the site, like links to subversion, except that developers might already
be used to finding it on the primary site. Which is precisely why, when
a new project asks how to post its nightly documentation, we should tell
them the best practice is to confine pre-release stuff to the developer
portion of the site. There they can post it as individual pages,
archives, a big PDF or whatever. We can keep this line clear: if it's
content destined for release but that hasn't been released, it should
only be available from the developer portion of the site.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Joe Schaefer <jo...@yahoo.com>.
----- Original Message ----
> From: Paul Querna <pa...@querna.org>
> To: general@incubator.apache.org
> Sent: Mon, December 7, 2009 5:34:18 PM
> Subject: Re: Publishing api docs for Subversion
>
> On Mon, Dec 7, 2009 at 1:00 PM, Doug Cutting wrote:
> > William A. Rowe Jr. wrote:
> >>
> >> I suspect that renaming /docs/trunk/ to /docs/dev/ would be sufficient and
> >> follow this best practice?
> >
> > I don't know how much folks look at the URL, but I think I've heard Roy
> > indicate that all developer-specific stuff should be under a dev/ URL.
> >
> > I think it would be better yet not to link to it from the side bar, which
> > appears on every page, but rather just from the http://httpd.apache.org/dev/
> > page. If the primary point of posting it is so that developers can refer to
> > it without having to build it themselves, it doesn't need to be posted so
> > prominently, does it?
>
> But in a way, its still missing a point -- because the other
> documentation URL,s, IE for 2.2.x, are direct subversion exports, with
> no voting on their contents, so its really a branches/2.2.x/docs
> instead of trunk/docs.
>
> I think the stance being taken understandable, but I believe the
> burden is being placed completely in the wrong direction. Make things
> easier to do, not harder.
>
> IANAL, but whats so bad from the ASF liability standpoint that
> requires voting on website content? if there is ever a problem, we
> pull it.....
Exactly. That's the key difference between a release and a website, we
can't take the release back. I honestly can't think of a reason we'd be
successfully sued for actual website content unless we failed to pull down
the offending material once notified of the breech.
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Paul Querna <pa...@querna.org>.
On Mon, Dec 7, 2009 at 1:00 PM, Doug Cutting <cu...@apache.org> wrote:
> William A. Rowe Jr. wrote:
>>
>> I suspect that renaming /docs/trunk/ to /docs/dev/ would be sufficient and
>> follow this best practice?
>
> I don't know how much folks look at the URL, but I think I've heard Roy
> indicate that all developer-specific stuff should be under a dev/ URL.
>
> I think it would be better yet not to link to it from the side bar, which
> appears on every page, but rather just from the http://httpd.apache.org/dev/
> page. If the primary point of posting it is so that developers can refer to
> it without having to build it themselves, it doesn't need to be posted so
> prominently, does it?
But in a way, its still missing a point -- because the other
documentation URL,s, IE for 2.2.x, are direct subversion exports, with
no voting on their contents, so its really a branches/2.2.x/docs
instead of trunk/docs.
I think the stance being taken understandable, but I believe the
burden is being placed completely in the wrong direction. Make things
easier to do, not harder.
IANAL, but whats so bad from the ASF liability standpoint that
requires voting on website content? if there is ever a problem, we
pull it.....
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Branko Čibej <br...@xbc.nu>.
Doug Cutting wrote:
> William A. Rowe Jr. wrote:
>> I suspect that renaming /docs/trunk/ to /docs/dev/ would be
>> sufficient and
>> follow this best practice?
>
> I don't know how much folks look at the URL, but I think I've heard
> Roy indicate that all developer-specific stuff should be under a dev/
> URL.
>
> I think it would be better yet not to link to it from the side bar,
> which appears on every page, but rather just from the
> http://httpd.apache.org/dev/ page. If the primary point of posting it
> is so that developers can refer to it without having to build it
> themselves, it doesn't need to be posted so prominently, does it?
The question is /which/ developers. If you insist that trunk
documentation is for contributors to the project only ... then I beg to
differ. It's a very useful resource. Making it harder to find is less
than friendly.
On the other hand, in this day of massive search engines, it doesn't
really matter where you put the generated documentation -- it gets
indexed one way or another. Unless you're now going to say that the dev/
part of the site alsy needs its own robots.txt that prevents indexing by
search engines. :)
-- Brane
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
William A. Rowe Jr. wrote:
> I suspect that renaming /docs/trunk/ to /docs/dev/ would be sufficient and
> follow this best practice?
I don't know how much folks look at the URL, but I think I've heard Roy
indicate that all developer-specific stuff should be under a dev/ URL.
I think it would be better yet not to link to it from the side bar,
which appears on every page, but rather just from the
http://httpd.apache.org/dev/ page. If the primary point of posting it
is so that developers can refer to it without having to build it
themselves, it doesn't need to be posted so prominently, does it?
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by "William A. Rowe Jr." <wr...@rowe-clan.net>.
Doug Cutting wrote:
> Branko Čibej wrote:
>> So I'm not too clear on what your objections are.
>> * Do you object to publishing non-released documentation on the
>> project Web pages?
>
> I object to posting these outside of a clearly-marked developer portion
> of the project's web site.
>
>> Then you should start by cleaning up the
>> existing ASF TLPs; begin with HTTPD, for example.
>
> I am here responding to a question about an incubating project, not
> about HTTPD. I agree that HTTPD does not appear to be following
> best-practice here. All other developer-specific links for HTTPD seem
> to be in http://httpd.apache.org/dev/. This one should be too, although
> the sidebar link does at least have "dev" in it.
I suspect that renaming /docs/trunk/ to /docs/dev/ would be sufficient and
follow this best practice?
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Branko Čibej wrote:
> So I'm not too clear on what your objections are.
> * Do you object to publishing non-released documentation on the
> project Web pages?
I object to posting these outside of a clearly-marked developer portion
of the project's web site.
> Then you should start by cleaning up the
> existing ASF TLPs; begin with HTTPD, for example.
I am here responding to a question about an incubating project, not
about HTTPD. I agree that HTTPD does not appear to be following
best-practice here. All other developer-specific links for HTTPD seem
to be in http://httpd.apache.org/dev/. This one should be too, although
the sidebar link does at least have "dev" in it.
> * Do you object to publishing the link and not marking it as
> "development" or "unstable" or whatever? AFAICS nobody suggested that.
I think the best practice is not merely to mark such links, but to put
all developer-specific links in a separate section of the website for
developers.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Branko Čibej <br...@xbc.nu>.
Doug Cutting wrote:
> Niall Pemberton wrote:
>> I would prefer what I say isn't distorted by selective editing.
>
> Sorry, that was not my intent.
>
>>> I'm not talking about the website in general. I'm talking specifically
>>> about publishing content primarily intended for inclusion in
>>> releases. Would
>>
>> Publication & release are two different things - thats the point.
>
> I don't see that yet. Can you tell me more about the difference? I
> use "publish", "distribute" and "release" more or less synonymously
> when referring to project content. Subversion contains only working
> drafts.
>
>>> we permit someone to mirror other files from trunk on the website?
>>> What's
>>
>> Yes and I bet every project provides a link to browse subversion which
>> itself is just another web site.
>
> Yes, but such links are meant to be confined to developer-oriented
> pages. We specifically do not encourage anyone but developers to use
> code in subversion. We provide extra diligence for releases, and that
> only makes sense if we don't otherwise distribute their content to the
> general public. Subversion is a service for our developers.
The ViewVC pages are publicly accessible. Therefore they are a service
for the whole world, not just for our developers; just like the project
web sites. I find myself quite often looking at sources and mainline
documentation for projects where I'm not a developer. Most of the time,
such resources are marked as unstable in some way, and not just in
Apache-hosted projects. That's as it should be.
So I'm not too clear on what your objections are.
* Do you object to publishing non-released documentation on the
project Web pages? Then you should start by cleaning up the
existing ASF TLPs; begin with HTTPD, for example.
* Do you object to publishing the link and not marking it as
"development" or "unstable" or whatever? AFAICS nobody suggested that.
-- Brane
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Niall Pemberton wrote:
> I would prefer what I say isn't distorted by selective editing.
Sorry, that was not my intent.
>> I'm not talking about the website in general. I'm talking specifically
>> about publishing content primarily intended for inclusion in releases. Would
>
> Publication & release are two different things - thats the point.
I don't see that yet. Can you tell me more about the difference? I use
"publish", "distribute" and "release" more or less synonymously when
referring to project content. Subversion contains only working drafts.
>> we permit someone to mirror other files from trunk on the website? What's
>
> Yes and I bet every project provides a link to browse subversion which
> itself is just another web site.
Yes, but such links are meant to be confined to developer-oriented
pages. We specifically do not encourage anyone but developers to use
code in subversion. We provide extra diligence for releases, and that
only makes sense if we don't otherwise distribute their content to the
general public. Subversion is a service for our developers.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Niall Pemberton <ni...@gmail.com>.
On Fri, Dec 4, 2009 at 11:45 PM, Doug Cutting <cu...@apache.org> wrote:
> Niall Pemberton wrote:
>>
>> What we publish on the ASF websites
>> doesn't have to conform to the licensing policy that releases do.
I would prefer what I say isn't distorted by selective editing.
> I'm not talking about the website in general. I'm talking specifically
> about publishing content primarily intended for inclusion in releases. Would
Publication & release are two different things - thats the point.
> we permit someone to mirror other files from trunk on the website? What's
Yes and I bet every project provides a link to browse subversion which
itself is just another web site.
> special about documentation? It comes from contributors, we require an ICLA
Everything is contributed by someone, including the web site contents.
Niall
> or some other indication of intent to submit under the Apache license, its
> changes are subject to vetos, etc. It's otherwise treated just like code.
>
> Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Niall Pemberton wrote:
> What we publish on the ASF websites
> doesn't have to conform to the licensing policy that releases do.
I'm not talking about the website in general. I'm talking specifically
about publishing content primarily intended for inclusion in releases.
Would we permit someone to mirror other files from trunk on the website?
What's special about documentation? It comes from contributors, we
require an ICLA or some other indication of intent to submit under the
Apache license, its changes are subject to vetos, etc. It's otherwise
treated just like code.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Niall Pemberton <ni...@gmail.com>.
On Fri, Dec 4, 2009 at 9:09 PM, Doug Cutting <cu...@apache.org> wrote:
> Niall Pemberton wrote:
>>
>> It might be good a good idea to not confuse users trying to find docs
>> that relate to a release from that of of the current trunk, but its
>> doing incubating projects a disservice to try and make out that
>> release policy cover the docs they publish on their web site.
>
> Don't our release policies cover all the stuff that's in releases and
> derivations thereof? What's the rationale to separate documentation from
> everything else that's in a release?
Yes but this is not talking about releases - its about publishing
documentation on the web site. Thats not what everyone understands by
the term *release* here. We don't vote every time someone wants to
republish the website. Its not inviting people to take something away
and do what they want with it. What we publish on the ASF websites
doesn't have to conform to the licensing policy that releases do. Its
there for people to read. Now if you packaged up those docs, voted on
them to distribute and invited people to download them and what
they're licensed under then it would be a release. But this isn't
that, its providing documentation on the website and AIUI that isn't
governed by what we have for a release policy.
Niall
>> This is
>> something for the project to decide for themselves and we should keep
>> our noses out and avoid trying to find new ways to beat them up with
>> policy.
>
> I'm actually trying to keep the policy straightforward and consistent: ASF
> content that's subject to release votes should only be published to
> non-developers after it's been released. Posting trunk documentation seems
> very similar to posting a nightly build. Both are permitted, but not only
> via developer-specific pages, not in a way that can be construed as an
> official distribution.
>
> Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Niall Pemberton wrote:
> It might be good a good idea to not confuse users trying to find docs
> that relate to a release from that of of the current trunk, but its
> doing incubating projects a disservice to try and make out that
> release policy cover the docs they publish on their web site.
Don't our release policies cover all the stuff that's in releases and
derivations thereof? What's the rationale to separate documentation
from everything else that's in a release?
> This is
> something for the project to decide for themselves and we should keep
> our noses out and avoid trying to find new ways to beat them up with
> policy.
I'm actually trying to keep the policy straightforward and consistent:
ASF content that's subject to release votes should only be published to
non-developers after it's been released. Posting trunk documentation
seems very similar to posting a nightly build. Both are permitted, but
not only via developer-specific pages, not in a way that can be
construed as an official distribution.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Niall Pemberton <ni...@gmail.com>.
On Fri, Dec 4, 2009 at 5:29 PM, Doug Cutting <cu...@apache.org> wrote:
> Paul Querna wrote:
>>
>> <http://httpd.apache.org/docs/trunk/>
>>
>> Which is linked from the sidebar everywhere, and on the docs page:
>> <http://httpd.apache.org/docs/>
>
> That trunk documentation is at least labelled "dev". I'd argue it should
> only be linked to from http://httpd.apache.org/dev/ and that it should
> reside there. That would be consistent with:
>
> http://www.apache.org/dev/release.html#what
>
> "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."
>
> Documentation that's released is released under the Apache license and is
> not in general strongly distinguished from code that's released: we require
> a CLA on file for documentation contributions, we require each documentation
> source file to contain the license, etc. Publishing trunk documentation to
> the non-developer portion of a web site is encouragement for non-developers
> to use trunk, which is something we should avoid.
It might be good a good idea to not confuse users trying to find docs
that relate to a release from that of of the current trunk, but its
doing incubating projects a disservice to try and make out that
release policy cover the docs they publish on their web site. This is
something for the project to decide for themselves and we should keep
our noses out and avoid trying to find new ways to beat them up with
policy.
Niall
> Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Paul Querna wrote:
> <http://httpd.apache.org/docs/trunk/>
>
> Which is linked from the sidebar everywhere, and on the docs page:
> <http://httpd.apache.org/docs/>
That trunk documentation is at least labelled "dev". I'd argue it
should only be linked to from http://httpd.apache.org/dev/ and that it
should reside there. That would be consistent with:
http://www.apache.org/dev/release.html#what
"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."
Documentation that's released is released under the Apache license and
is not in general strongly distinguished from code that's released: we
require a CLA on file for documentation contributions, we require each
documentation source file to contain the license, etc. Publishing trunk
documentation to the non-developer portion of a web site is
encouragement for non-developers to use trunk, which is something we
should avoid.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Paul Querna <pa...@querna.org>.
On Thu, Dec 3, 2009 at 9:31 AM, Doug Cutting <cu...@apache.org> wrote:
> Paul Querna wrote:
>>
>> httpd and apr have published doxygen of their trunks periodically,
>> they aren't based on any release.
>
> Were these published these on the official public website or in the dev/
> section?
>
> I was under the impression that released documentation should be treated
> similarly to released code. The convention I've used is that stuff that's
> in trunk, stuff that's intended to be included in releases, is only
> published after release. Other pages on the website that are not included
> in releases, e.g., the project's home page, are clearly published without a
> release vote.
<http://httpd.apache.org/docs/trunk/>
Which is linked from the sidebar everywhere, and on the docs page:
<http://httpd.apache.org/docs/>
> In particular, I think it's a bad practice to publish automatic nightly
> builds on the official website of content that's otherwise the subject of
> release votes. Is it forbidden? Perhaps not, but it's not a practice we
> should encourage in the incubator. Often documentation includes code. Do
> we want to publish that code without a vote?
httpd docs don't include code, dunno what projects do :)
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Paul Querna wrote:
> httpd and apr have published doxygen of their trunks periodically,
> they aren't based on any release.
Were these published these on the official public website or in the dev/
section?
I was under the impression that released documentation should be treated
similarly to released code. The convention I've used is that stuff
that's in trunk, stuff that's intended to be included in releases, is
only published after release. Other pages on the website that are not
included in releases, e.g., the project's home page, are clearly
published without a release vote.
In particular, I think it's a bad practice to publish automatic nightly
builds on the official website of content that's otherwise the subject
of release votes. Is it forbidden? Perhaps not, but it's not a
practice we should encourage in the incubator. Often documentation
includes code. Do we want to publish that code without a vote?
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Joe Schaefer <jo...@yahoo.com>.
A lot of our website stuff has peculiar licensing on it; and I don't
think anyone really cares whether or not a given webpage is Apache-licensed
or not. So I think Doug is stretching things a bit when he equates the
standards for software releases and standards for website publishing
(where we only assume Apache has a license to publish the content).
----- Original Message ----
> From: sebb <se...@gmail.com>
> To: general@incubator.apache.org
> Sent: Wed, December 2, 2009 9:31:25 PM
> Subject: Re: Publishing api docs for Subversion
>
> On 03/12/2009, Paul Querna wrote:
> > On Wed, Dec 2, 2009 at 10:17 AM, Doug Cutting wrote:
> > > Bhuvaneswaran A wrote:
> > >>
> > >> We tend to update the api docs generated using doxygen and java doc on
> > >> a nightly basis.
> > >
> > > Unreleased artifacts should be linked only from the developer portion of
> the
> > > site and should not be hosted on the official project site. You might,
> > > e.g., just link to them on the Hudson server rather than copy them to
> > > people.apache.org. Documentation should only be published to the official
> > > website after it's been included in an Apache release. This is for legal
> > > reasons: we work hard to ensure that releases have licensing in order, but
> > > do not in general guarantee that licensing is correct at all times in
> source
> > > code repositories.
> >
> >
> > I'm sorry what?
> >
> > httpd and apr have published doxygen of their trunks periodically,
> > they aren't based on any release.
>
> And large parts of the ASF website (which can be considered as
> documentation) are not subject to formal "release" votes.
>
> Doug's comments seem OK if they refer to code releases, but surely
> documentation is not subject to release votes?
>
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> > For additional commands, e-mail: general-help@incubator.apache.org
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Branko Čibej wrote:
> Actually, we're talking about API documentation which in Subversion's
> case is generated from the sources, so yes, it is subject to release
> votes. But only for actual releases.
>
> Restricting the publishing of generated API documentation would imply
> that we should restrict access to ViewVC, too, because anyone can browse
> that exact same documentation through that, albeit formatted a bit
> differently.
No, that's not required. The best practice for our official project
websites is to distinguish content that's intended for the general
public from content that's intended for developers. We should only link
to subversion and nightly builds from the developer portions of our
sites. We must, for example, not link to subversion or to nightly
builds from the release download page.
We have a two-step process for licensing. First, we try to make sure
that things are suitable for release before we commit them to
subversion. But some things fall through the cracks in this step.
Sometimes files lack license headers. Sometimes, especially in the
incubator, we'll commit something before we have all of the ICLA's on
file. Sometimes we commit software that we cannot release and must
remove. So as the second step, we review everything prior to release to
double-check that the licensing is correct.
Between these two steps the content is technically accessible by anyone,
but our legal claim is that we're not yet distributing it to the general
public under the Apache license, but only to our developers as a working
draft. To support this claim, we only link to pre-release content from
developer-specific portions of our sites. ViewVC is a developer tool,
not a tool we promote for use by the general public.
Posting content intended for release that has not cleared the second
hurdle bypasses the release process and should be avoided.
We do not have this two-step process for non-released website content.
Our project home pages are not formally released and we trust that folks
will be careful about what's posted there. But we should not use this
as a grounds to publish content that is otherwise subject to release to
the general public without a release vote.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Branko Čibej <br...@xbc.nu>.
sebb wrote:
> On 03/12/2009, Paul Querna <pa...@querna.org> wrote:
>
>> On Wed, Dec 2, 2009 at 10:17 AM, Doug Cutting <cu...@apache.org> wrote:
>> > Bhuvaneswaran A wrote:
>> >>
>> >> We tend to update the api docs generated using doxygen and java doc on
>> >> a nightly basis.
>> >
>> > Unreleased artifacts should be linked only from the developer portion of the
>> > site and should not be hosted on the official project site. You might,
>> > e.g., just link to them on the Hudson server rather than copy them to
>> > people.apache.org. Documentation should only be published to the official
>> > website after it's been included in an Apache release. This is for legal
>> > reasons: we work hard to ensure that releases have licensing in order, but
>> > do not in general guarantee that licensing is correct at all times in source
>> > code repositories.
>>
>>
>> I'm sorry what?
>>
>> httpd and apr have published doxygen of their trunks periodically,
>> they aren't based on any release.
>>
>
> And large parts of the ASF website (which can be considered as
> documentation) are not subject to formal "release" votes.
>
> Doug's comments seem OK if they refer to code releases, but surely
> documentation is not subject to release votes?
>
Actually, we're talking about API documentation which in Subversion's
case is generated from the sources, so yes, it is subject to release
votes. But only for actual releases.
Restricting the publishing of generated API documentation would imply
that we should restrict access to ViewVC, too, because anyone can browse
that exact same documentation through that, albeit formatted a bit
differently.
-- Brane
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by sebb <se...@gmail.com>.
On 03/12/2009, Paul Querna <pa...@querna.org> wrote:
> On Wed, Dec 2, 2009 at 10:17 AM, Doug Cutting <cu...@apache.org> wrote:
> > Bhuvaneswaran A wrote:
> >>
> >> We tend to update the api docs generated using doxygen and java doc on
> >> a nightly basis.
> >
> > Unreleased artifacts should be linked only from the developer portion of the
> > site and should not be hosted on the official project site. You might,
> > e.g., just link to them on the Hudson server rather than copy them to
> > people.apache.org. Documentation should only be published to the official
> > website after it's been included in an Apache release. This is for legal
> > reasons: we work hard to ensure that releases have licensing in order, but
> > do not in general guarantee that licensing is correct at all times in source
> > code repositories.
>
>
> I'm sorry what?
>
> httpd and apr have published doxygen of their trunks periodically,
> they aren't based on any release.
And large parts of the ASF website (which can be considered as
documentation) are not subject to formal "release" votes.
Doug's comments seem OK if they refer to code releases, but surely
documentation is not subject to release votes?
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Paul Querna <pa...@querna.org>.
On Wed, Dec 2, 2009 at 10:17 AM, Doug Cutting <cu...@apache.org> wrote:
> Bhuvaneswaran A wrote:
>>
>> We tend to update the api docs generated using doxygen and java doc on
>> a nightly basis.
>
> Unreleased artifacts should be linked only from the developer portion of the
> site and should not be hosted on the official project site. You might,
> e.g., just link to them on the Hudson server rather than copy them to
> people.apache.org. Documentation should only be published to the official
> website after it's been included in an Apache release. This is for legal
> reasons: we work hard to ensure that releases have licensing in order, but
> do not in general guarantee that licensing is correct at all times in source
> code repositories.
I'm sorry what?
httpd and apr have published doxygen of their trunks periodically,
they aren't based on any release.
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: Publishing api docs for Subversion
Posted by Doug Cutting <cu...@apache.org>.
Bhuvaneswaran A wrote:
> We tend to update the api docs generated using doxygen and java doc on
> a nightly basis.
Unreleased artifacts should be linked only from the developer portion of
the site and should not be hosted on the official project site. You
might, e.g., just link to them on the Hudson server rather than copy
them to people.apache.org. Documentation should only be published to
the official website after it's been included in an Apache release.
This is for legal reasons: we work hard to ensure that releases have
licensing in order, but do not in general guarantee that licensing is
correct at all times in source code repositories.
Doug
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org