Re: committing doc changes

[Michael Han]

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
 from the site's svn repo
, 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  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  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 
> wrote:
> > >
> > > > We currently do it for the trunk build:
> > > >
> > > > 
> > > >
> > > > but not for pull request or patch QA:
> > > >
> > > > 
> > > >
> > > > "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  wrote:
> > > > >
> > > > > we could also build the doc as part of the tests.
> > > > >
> > > > > On Wed, Nov 30, 2016 at 3:26 PM, Flavio Junqueira 
> > > > 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 
> 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
> > > > >>>  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 
> > > > 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.

Re: committing doc changes

[Abraham Fine]

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  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  wrote:
> >
> > > We currently do it for the trunk build:
> > >
> > > 
> > >
> > > but not for pull request or patch QA:
> > >
> > > 
> > >
> > > "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  wrote:
> > > >
> > > > we could also build the doc as part of the tests.
> > > >
> > > > On Wed, Nov 30, 2016 at 3:26 PM, Flavio Junqueira 
> > > 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  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
> > > >>>  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 
> > > 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.
> >

Re: committing doc changes

[Patrick Hunt]

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  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  wrote:
>
> > We currently do it for the trunk build:
> >
> > 
> >
> > but not for pull request or patch QA:
> >
> > 
> >
> > "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  wrote:
> > >
> > > we could also build the doc as part of the tests.
> > >
> > > On Wed, Nov 30, 2016 at 3:26 PM, Flavio Junqueira 
> > 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  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
> > >>>  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 
> > 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.
>

Re: committing doc changes

[Michael Han]

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  wrote:

> We currently do it for the trunk build:
>
> 
>
> but not for pull request or patch QA:
>
> 
>
> "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  wrote:
> >
> > we could also build the doc as part of the tests.
> >
> > On Wed, Nov 30, 2016 at 3:26 PM, Flavio Junqueira 
> 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  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
> >>>  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 
> 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.

Re: committing doc changes

[Flavio Junqueira]

We currently do it for the trunk build:



but not for pull request or patch QA:



"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  wrote:
> 
> we could also build the doc as part of the tests.
> 
> On Wed, Nov 30, 2016 at 3:26 PM, Flavio Junqueira  wrote:
>> As part of the release process, we only copy the documentation, see it here:
>> 
>> 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  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
>>>  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  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
 
>> 

Re: committing doc changes

[Benjamin Reed]

we could also build the doc as part of the tests.

On Wed, Nov 30, 2016 at 3:26 PM, Flavio Junqueira  wrote:
> As part of the release process, we only copy the documentation, see it here:
>
> 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  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
>>  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  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
>>>
>

Re: committing doc changes

[Flavio Junqueira]

As part of the release process, we only copy the documentation, see it here:

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

Re: committing doc changes

[Benjamin Reed]

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

Re: committing doc changes

[Michael Han]

+1 on the idea of separating doc source change with doc binary change.
Actually, should we just remove the binary doc from source repository given
they are artifacts that's only relevant to a release build (instead of
source)?

On Wed, Nov 30, 2016 at 2:24 PM, Jordan Zimmerman <
jor...@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  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.

Re: committing doc changes

[Jordan Zimmerman]

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