zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Han <h...@cloudera.com>
Subject Re: committing doc changes
Date Thu, 11 May 2017 20:14:46 GMT
I suspect removing of the compiled doc from git source repo will not break
https://zookeeper.apache.org/ because we publish the web site through CMS
<https://cms.apache.org/> from the site's svn repo
<https://svn.apache.org/repos/asf/zookeeper/site>, which is a separate
repo. So I am +1 with this proposal, but I'd like to hear what Flavio / Pat
/ Ben and other PMC thinks as I don't have the full history of how the site
works.

A side note is the current trunk doc is out of date, and the API doc link
is broken. The last time trunk doc was committed to the site svn repo was
2014 when dynamic reconfig doc was added.


On Fri, Apr 28, 2017 at 12:50 PM, Abraham Fine <afine@apache.org> wrote:

> Apologies for reviving an old thread.
>
> I'm wondering if we can make this conversation actionable. It would be
> great to remove the compiled documentation from the repository. I
> created a JIRA to cover this work:
> https://issues.apache.org/jira/browse/ZOOKEEPER-2769
>
> Does anyone have any insight into what would be required to make sure
> the trunk documentation remains available if we make this change. I do
> not believe I have access to the trunk jenkins job configuration to see
> exactly what is going on.
>
> Thanks,
> Abe
>
>
> On Mon, Dec 5, 2016, at 16:10, Patrick Hunt wrote:
> > As Flavio mentioned we (committers) commit the docs so that users
> > interested in d/l the source and using it don't need to generate the
> > docs,
> > which requires forrest and could often be a pita. In the early days this
> > was seen as a benefit. That's the history at least.
> >
> > Patrick
> >
> > On Thu, Dec 1, 2016 at 12:09 PM, Michael Han <hanm@cloudera.com> wrote:
> >
> > > Run forrest check only take a few seconds, so it seems worthwhile to
> add it
> > > to QA target to have some sanity checks on the doc change.
> > >
> > > On Thu, Dec 1, 2016 at 3:20 AM, Flavio Junqueira <fpj@apache.org>
> wrote:
> > >
> > > > We currently do it for the trunk build:
> > > >
> > > > <target name="hudson-test-trunk" depends="docs,tar,findbugs"/>
> > > >
> > > > but not for pull request or patch QA:
> > > >
> > > > <target name="qa-test-pullrequest" depends="findbugs.check,
> > > forrest.check">
> > > >
> > > > "forrest.check" only checks if the forrest.home variable is defined.
> > > >
> > > > Is that enough that we run it as part of the trunk build?
> > > >
> > > > -Flavio
> > > >
> > > > > On 01 Dec 2016, at 01:04, Benjamin Reed <breed@apache.org>
wrote:
> > > > >
> > > > > we could also build the doc as part of the tests.
> > > > >
> > > > > On Wed, Nov 30, 2016 at 3:26 PM, Flavio Junqueira <fpj@apache.org>
> > > > wrote:
> > > > >> As part of the release process, we only copy the documentation,
> see it
> > > > here:
> > > > >>
> > > > >> https://cwiki.apache.org/confluence/display/ZOOKEEPER/
> HowToRelease <
> > > > https://cwiki.apache.org/confluence/display/ZOOKEEPER/HowToRelease>
> > > > >>
> > > > >> I think the reason we have gone this way is to avoid issues
> compiling
> > > > the documentation at the time that we are preparing a release
> candidate
> > > or
> > > > after voting on a release candidate. We could for sure build the
> > > > documentation right before generating the first rc for a release and
> > > create
> > > > blocker jiras in the case there is any issue.
> > > > >>
> > > > >> -Flavio
> > > > >>
> > > > >>> On 30 Nov 2016, at 23:12, Benjamin Reed <breed@apache.org>
> wrote:
> > > > >>>
> > > > >>> yeah, that's a deeper question. pat or flavio can correct
me on
> this,
> > > > >>> but i think the reason we check it in is so that the website's
> > > "trunk"
> > > > >>> documentation will work. now that we moved to git, i don't
thing
> it
> > > > >>> works though... i also would just like to only build it when
we
> do
> > > > >>> releases.
> > > > >>>
> > > > >>> On Wed, Nov 30, 2016 at 2:24 PM, Jordan Zimmerman
> > > > >>> <jordan@jordanzimmerman.com> wrote:
> > > > >>>> I wondered about that myself. Why bother building the
docs?
> Isn’t
> > > > that only needed for packaging/deployment? It ends up making PRs ugly
> > > > because you have all the unnecessary docs in the diff.
> > > > >>>>
> > > > >>>> -Jordan
> > > > >>>>
> > > > >>>>> On Nov 30, 2016, at 11:23 PM, Benjamin Reed <breed@apache.org>
> > > > wrote:
> > > > >>>>>
> > > > >>>>> when we commit pull requests with doc changes, i
think we
> should
> > > > >>>>> commit the generated doc as a separate commit. what
do you all
> > > think?
> > > > >>>>> i would like to do that to keep the change from the
> contributors
> > > > >>>>> pristine :) and i think it simplifies things a bit.
> > > > >>>>>
> > > > >>>>> ben
> > > > >>>>
> > > > >>
> > > >
> > > >
> > >
> > >
> > > --
> > > Cheers
> > > Michael.
> > >
>



-- 
Cheers
Michael.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message