You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geode.apache.org by Dave Barnes <db...@apache.org> on 2022/06/14 19:03:39 UTC
[PROPOSAL] Relocate Geode Docs from code repo to seperate repo
I'd like to move the doc sources for the Geode User Guide from the code
repo (https://github.com/apache/geode) to a separate geode-docs repo.
The primary reason is to allow docs to cycle at their own rate, rather than
in lock-step with the code. The present arrangement causes problems during
releases, when code is frozen (including doc sources) to prepare a release
candidate. This is exactly the time when critical last-minute doc changes
are needed, but such changes are forbidden due to the code freeze.
I have participated in the Geode project since its inception, and can
confidently state that this conflict arises with nearly every Geode
release. Setting up the docs in a separate repo would alleviate this
regularly-recurring, counter-intuitive situation.
Of note: The docs directories and toolset are almost entirely independent
of directories and tools needed for code development and release, so
removal of the doc sources from the Geode code repo should be painless for
developers.
Observations and opinions welcome...
Dave Barnes
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Jacob Barrett <ja...@vmware.com.INVALID>.
I don’t see any downsides to this approach. We already do this for other assets like examples, native, site, and benchmarks.
> On Jun 14, 2022, at 12:03 PM, Dave Barnes <db...@apache.org> wrote:
>
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjabarrett%40vmware.com%7C79019270b63a4ee130ba08da4e3a2c77%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908309002941176%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=YMlTGuvk%2FU1bbW7%2F60bhMcO09PKcE3Tb2ew3ymlKySw%3D&reserved=0) to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
>
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
>
> Observations and opinions welcome...
>
> Dave Barnes
>
> ________________________________
>
> ⚠ External Email: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender.
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Alberto Gomez <al...@est.tech>.
Hi,
I agree with Udo and John that having the docs and the code in the same repo really helps to have both in-sync. Therefore, I would not separate them in different repos.
I'd rather see a change in the process to overcome the difficulties faced with the documentation after the code is frozen.
Alberto
________________________________
From: Udo Kohlmeyer <ud...@vmware.com.INVALID>
Sent: Wednesday, June 15, 2022 5:05 AM
To: dev@geode.apache.org <de...@geode.apache.org>
Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Hi there Dave,
I can understand the frustration that you face. I think the freezing of the code is different to that of the docs. I think each project member would agree if I stated that changes to the docs on ANY branch should be allowed regardless of where in the process of the release the project finds itself. (within common sense reasoning of course 😉 )
I am however interested in how we would ensure that the docs repo and the code repo, stay “in-sync”? Would we raise JIRA’s (Github issues) with the repo to make sure that we don’t miss documenting features or changes? We already suffer the problem where feature/changes are made and merged without sufficient docs changes. It feels like moving docs to their own repo would move a existing problem further away.
I understand that moving the docs to another repo, would enable some form of autonomy, but I believe that John might have a point, this feels very much like a process problem.
Would it help, if docs have a “special pass” that allows doc modifications to happen at any point on any branch, if the changes made relate to actual changes that have been completed on the branch? (to avoid docs changes that are out of sequence with the deliverable)
--Udo
From: Dave Barnes <db...@apache.org>
Date: Wednesday, June 15, 2022 at 8:11 AM
To: jblum@vmware.com.invalid <jb...@vmware.com.invalid>
Cc: dev@geode.apache.org <de...@geode.apache.org>
Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
⚠ External Email
John,
Thanks for acknowledging that docs are just as important as code! As a
career tech-writer, the "docs=code" model appeals to me.
I get what you're saying, and have worked in environments where release
managers have enforced such constraints.
In this vein, the Geode code is well-supplied with embedded Javadoc
comments that behave exactly as you describe, providing a reference that is
updated as the code is updated.
The difference with a user guide (as opposed to reference material), is
that examples and usage guidelines can be finalized only AFTER the code,
with all its version numbers, naming conventions, etc, are in place.
Delaying code freeze until docs are complete, in my experience, engenders
feature-creep and introduces delays, often resulting in compromises that
allow the release to go out with mis-matched docs. IMO, a separate
user-guide repo promotes a better and more timely match-up between the
software and the user guide.
On Tue, Jun 14, 2022 at 1:15 PM John Blum <jb...@vmware.com.invalid> wrote:
> Personally, I believe doc is a critical component to any software project,
> especially a project like Apache Geode, and so, is the project really
> “complete “(or should thee codebase really be frozen during a release) if
> the doc is not done or consistent yet?
>
> Having the doc be part of the source allows the doc to be (theoretically)
> in-sync with the codebase as it evolves, as it should be. On the other
> hand, with a separate repo, it does allow corrections or other alterations
> to be made at the risk of growing inconsistency, which is a huge impediment
> IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> interfaces).
>
> Ideally, I don’t see code and doc being separate or even fundamentally
> different.
>
> This sounds more like a process problem and a workaround to a broken
> process, to me.
>
> $0.02
> -John
>
>
> From: Dave Barnes <db...@apache.org>
> Date: Tuesday, June 14, 2022 at 12:15 PM
> To: dev@geode.apache.org <de...@geode.apache.org>
> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cudo%40vmware.com%7Ce50d39b82ffd499d21d708da4e52c36b%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908414625879240%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=3SKtmt7VI2tBelJRj48xqtW5x%2F9hYNzqFVX9NJe9IC0%3D&reserved=0)
> to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
>
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
>
> Observations and opinions welcome...
>
> Dave Barnes
>
> ________________________________
>
> ⚠ External Email: This email originated from outside of the organization.
> Do not click links or open attachments unless you recognize the sender.
>
________________________________
⚠ External Email: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender.
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Udo Kohlmeyer <ud...@vmware.com.INVALID>.
Hi there Dave,
I can understand the frustration that you face. I think the freezing of the code is different to that of the docs. I think each project member would agree if I stated that changes to the docs on ANY branch should be allowed regardless of where in the process of the release the project finds itself. (within common sense reasoning of course 😉 )
I am however interested in how we would ensure that the docs repo and the code repo, stay “in-sync”? Would we raise JIRA’s (Github issues) with the repo to make sure that we don’t miss documenting features or changes? We already suffer the problem where feature/changes are made and merged without sufficient docs changes. It feels like moving docs to their own repo would move a existing problem further away.
I understand that moving the docs to another repo, would enable some form of autonomy, but I believe that John might have a point, this feels very much like a process problem.
Would it help, if docs have a “special pass” that allows doc modifications to happen at any point on any branch, if the changes made relate to actual changes that have been completed on the branch? (to avoid docs changes that are out of sequence with the deliverable)
--Udo
From: Dave Barnes <db...@apache.org>
Date: Wednesday, June 15, 2022 at 8:11 AM
To: jblum@vmware.com.invalid <jb...@vmware.com.invalid>
Cc: dev@geode.apache.org <de...@geode.apache.org>
Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
⚠ External Email
John,
Thanks for acknowledging that docs are just as important as code! As a
career tech-writer, the "docs=code" model appeals to me.
I get what you're saying, and have worked in environments where release
managers have enforced such constraints.
In this vein, the Geode code is well-supplied with embedded Javadoc
comments that behave exactly as you describe, providing a reference that is
updated as the code is updated.
The difference with a user guide (as opposed to reference material), is
that examples and usage guidelines can be finalized only AFTER the code,
with all its version numbers, naming conventions, etc, are in place.
Delaying code freeze until docs are complete, in my experience, engenders
feature-creep and introduces delays, often resulting in compromises that
allow the release to go out with mis-matched docs. IMO, a separate
user-guide repo promotes a better and more timely match-up between the
software and the user guide.
On Tue, Jun 14, 2022 at 1:15 PM John Blum <jb...@vmware.com.invalid> wrote:
> Personally, I believe doc is a critical component to any software project,
> especially a project like Apache Geode, and so, is the project really
> “complete “(or should thee codebase really be frozen during a release) if
> the doc is not done or consistent yet?
>
> Having the doc be part of the source allows the doc to be (theoretically)
> in-sync with the codebase as it evolves, as it should be. On the other
> hand, with a separate repo, it does allow corrections or other alterations
> to be made at the risk of growing inconsistency, which is a huge impediment
> IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> interfaces).
>
> Ideally, I don’t see code and doc being separate or even fundamentally
> different.
>
> This sounds more like a process problem and a workaround to a broken
> process, to me.
>
> $0.02
> -John
>
>
> From: Dave Barnes <db...@apache.org>
> Date: Tuesday, June 14, 2022 at 12:15 PM
> To: dev@geode.apache.org <de...@geode.apache.org>
> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cudo%40vmware.com%7Ce50d39b82ffd499d21d708da4e52c36b%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908414625879240%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=3SKtmt7VI2tBelJRj48xqtW5x%2F9hYNzqFVX9NJe9IC0%3D&reserved=0)
> to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
>
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
>
> Observations and opinions welcome...
>
> Dave Barnes
>
> ________________________________
>
> ⚠ External Email: This email originated from outside of the organization.
> Do not click links or open attachments unless you recognize the sender.
>
________________________________
⚠ External Email: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender.
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Dave Barnes <db...@apache.org>.
Good arguments on both sides, but not an overwhelming consensus.
I will leave things as they are. Thanks for everyone who contributed to the
discussion!
On Fri, Jun 17, 2022 at 6:37 AM Alberto Gomez <al...@est.tech>
wrote:
> Hi Dave,
>
> Supposing we move the documentation out of the geode code repo, if I
> download a certain release of Geode, how do I know which version of the
> documentation I must download which will be consistent with the code?
>
> Having both the docs and the code in the same repo makes the above
> question a no-brainer. But if code and documentation do not go hand by
> hand, how will we know?
>
> Alberto
> ________________________________
> From: Dave Barnes <db...@apache.org>
> Sent: Wednesday, June 15, 2022 11:06 PM
> To: dev@geode.apache.org <de...@geode.apache.org>
> Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
>
> Adopting a policy that allows changes to doc sources after code freeze
> would address my primary complaint about the present system.
> Updating the User Guide at the time a user-visible code change is
> implemented is a helpful step toward keeping the docs up-to-date with the
> code, but is not sufficient.
> Above and beyond individual enhancements, the user guide addresses topics
> such as system configuration, upgrades, and the like. Such higher-level
> topics are often modified asynchronously from code releases, as are typo
> and format repairs. For such asynchronous updates, the fact that the doc
> sources are located in the source repo is of little consequence. In fact,
> separate repos would allow separate revision histories, an advantage to
> both.
> One more consideration is the possibility of breaking the monolithic user
> guide into smaller separate publications, such as an installation guide,
> system management/administration guide, developer's guide, advanced topics,
> etc. A change like this would be easier if it started from a docs-only
> repo.
> Did any of those thoughts change anyone's mind?
>
> On Wed, Jun 15, 2022 at 12:29 AM Owen Nichols <onichols@vmware.com.invalid
> >
> wrote:
>
> > The Geode project comprises several repos already, include geode,
> > geode-examples, geode-benchmarks, geode-native, and
> geode-kafka-connector,
> > and geode-site, so it’s not unreasonable to add another. However, we
> still
> > release all at the same time, so any “code freeze” applies equally to all
> > geode repos.
> >
> > Conceptually, “code freeze” applies to *code we ship*. Test-only or
> > docs-only commits are welcome anytime. Actually, any commits are welcome
> at
> > any time -- “freeze” just means the branch is tagged at the point in time
> > the release manager creates RC1; any commits after that tag will simply
> > become part of a future release (in the event we go to RC2, post-freeze
> > commits may or may not be pulled into the current release, at the release
> > manager’s discretion).
> >
> > Although the User Guide source files are currently part of the Geode
> > source release, most users probably find the published website [1] more
> > convenient. In my opinion, it should be fine to publish improvements to
> > the doc site post-release (taking care to exclude commits related to
> > unreleased new features, if any)...would that resolve the issue?
> >
> > > examples and usage guidelines can be finalized only AFTER the code,
> with
> > all its version numbers, naming conventions, etc, are in place.
> > Chasing a moving target is definitely be frustrating; luckily there are
> > things we can all do to minimize it. I’ve seen many PRs that update the
> > docs at the same time as they change the product -- reviewers should
> check
> > for this when reviewing any PR that affects a public API, config setting,
> > etc. We also cut the support branch well in advance of planned release
> > date and limit changes on the support branch to critical fixes only.
> > Whenever necessary, anyone should feel free to file blocker tickets for
> > missing/incorrect docs to ensure the release does not ship prematurely
> > without meeting Geode’s standard of documentation.
> > [1] https://geode.apache.org/docs/
> >
> > From: Dave Barnes <db...@apache.org>
> > Date: Tuesday, June 14, 2022 at 3:11 PM
> > To: jblum@vmware.com.invalid <jb...@vmware.com.INVALID>
> > Cc: dev@geode.apache.org <de...@geode.apache.org>
> > Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate
> repo
> > ⚠ External Email
> >
> > John,
> > Thanks for acknowledging that docs are just as important as code! As a
> > career tech-writer, the "docs=code" model appeals to me.
> > I get what you're saying, and have worked in environments where release
> > managers have enforced such constraints.
> > In this vein, the Geode code is well-supplied with embedded Javadoc
> > comments that behave exactly as you describe, providing a reference that
> is
> > updated as the code is updated.
> > The difference with a user guide (as opposed to reference material), is
> > that examples and usage guidelines can be finalized only AFTER the code,
> > with all its version numbers, naming conventions, etc, are in place.
> > Delaying code freeze until docs are complete, in my experience, engenders
> > feature-creep and introduces delays, often resulting in compromises that
> > allow the release to go out with mis-matched docs. IMO, a separate
> > user-guide repo promotes a better and more timely match-up between the
> > software and the user guide.
> >
> >
> > On Tue, Jun 14, 2022 at 1:15 PM John Blum <jb...@vmware.com.invalid>
> > wrote:
> >
> > > Personally, I believe doc is a critical component to any software
> > project,
> > > especially a project like Apache Geode, and so, is the project really
> > > “complete “(or should thee codebase really be frozen during a release)
> > if
> > > the doc is not done or consistent yet?
> > >
> > > Having the doc be part of the source allows the doc to be
> (theoretically)
> > > in-sync with the codebase as it evolves, as it should be. On the other
> > > hand, with a separate repo, it does allow corrections or other
> > alterations
> > > to be made at the risk of growing inconsistency, which is a huge
> > impediment
> > > IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> > > interfaces).
> > >
> > > Ideally, I don’t see code and doc being separate or even fundamentally
> > > different.
> > >
> > > This sounds more like a process problem and a workaround to a broken
> > > process, to me.
> > >
> > > $0.02
> > > -John
> > >
> > >
> > > From: Dave Barnes <db...@apache.org>
> > > Date: Tuesday, June 14, 2022 at 12:15 PM
> > > To: dev@geode.apache.org <de...@geode.apache.org>
> > > Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> > > ⚠ External Email
> > >
> > > I'd like to move the doc sources for the Geode User Guide from the code
> > > repo (
> > >
> >
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Conichols%40vmware.com%7C90f35f9a69e9429c221c08da4e52c542%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908414805059869%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=w%2FOjA9CKepainPMniHOjz0kJ5TZE7VCFOetwcIojwsE%3D&reserved=0
> > )
> > > to a separate geode-docs repo.
> > >
> > > The primary reason is to allow docs to cycle at their own rate, rather
> > than
> > > in lock-step with the code. The present arrangement causes problems
> > during
> > > releases, when code is frozen (including doc sources) to prepare a
> > release
> > > candidate. This is exactly the time when critical last-minute doc
> changes
> > > are needed, but such changes are forbidden due to the code freeze.
> > >
> > > I have participated in the Geode project since its inception, and can
> > > confidently state that this conflict arises with nearly every Geode
> > > release. Setting up the docs in a separate repo would alleviate this
> > > regularly-recurring, counter-intuitive situation.
> > >
> > > Of note: The docs directories and toolset are almost entirely
> independent
> > > of directories and tools needed for code development and release, so
> > > removal of the doc sources from the Geode code repo should be painless
> > for
> > > developers.
> > >
> > > Observations and opinions welcome...
> > >
> > > Dave Barnes
> > >
> > > ________________________________
> > >
> > > ⚠ External Email: This email originated from outside of the
> organization.
> > > Do not click links or open attachments unless you recognize the sender.
> > >
> >
> > ________________________________
> >
> > ⚠ External Email: This email originated from outside of the organization.
> > Do not click links or open attachments unless you recognize the sender.
> >
>
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Alberto Gomez <al...@est.tech>.
Hi Dave,
Supposing we move the documentation out of the geode code repo, if I download a certain release of Geode, how do I know which version of the documentation I must download which will be consistent with the code?
Having both the docs and the code in the same repo makes the above question a no-brainer. But if code and documentation do not go hand by hand, how will we know?
Alberto
________________________________
From: Dave Barnes <db...@apache.org>
Sent: Wednesday, June 15, 2022 11:06 PM
To: dev@geode.apache.org <de...@geode.apache.org>
Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Adopting a policy that allows changes to doc sources after code freeze
would address my primary complaint about the present system.
Updating the User Guide at the time a user-visible code change is
implemented is a helpful step toward keeping the docs up-to-date with the
code, but is not sufficient.
Above and beyond individual enhancements, the user guide addresses topics
such as system configuration, upgrades, and the like. Such higher-level
topics are often modified asynchronously from code releases, as are typo
and format repairs. For such asynchronous updates, the fact that the doc
sources are located in the source repo is of little consequence. In fact,
separate repos would allow separate revision histories, an advantage to
both.
One more consideration is the possibility of breaking the monolithic user
guide into smaller separate publications, such as an installation guide,
system management/administration guide, developer's guide, advanced topics,
etc. A change like this would be easier if it started from a docs-only repo.
Did any of those thoughts change anyone's mind?
On Wed, Jun 15, 2022 at 12:29 AM Owen Nichols <on...@vmware.com.invalid>
wrote:
> The Geode project comprises several repos already, include geode,
> geode-examples, geode-benchmarks, geode-native, and geode-kafka-connector,
> and geode-site, so it’s not unreasonable to add another. However, we still
> release all at the same time, so any “code freeze” applies equally to all
> geode repos.
>
> Conceptually, “code freeze” applies to *code we ship*. Test-only or
> docs-only commits are welcome anytime. Actually, any commits are welcome at
> any time -- “freeze” just means the branch is tagged at the point in time
> the release manager creates RC1; any commits after that tag will simply
> become part of a future release (in the event we go to RC2, post-freeze
> commits may or may not be pulled into the current release, at the release
> manager’s discretion).
>
> Although the User Guide source files are currently part of the Geode
> source release, most users probably find the published website [1] more
> convenient. In my opinion, it should be fine to publish improvements to
> the doc site post-release (taking care to exclude commits related to
> unreleased new features, if any)...would that resolve the issue?
>
> > examples and usage guidelines can be finalized only AFTER the code, with
> all its version numbers, naming conventions, etc, are in place.
> Chasing a moving target is definitely be frustrating; luckily there are
> things we can all do to minimize it. I’ve seen many PRs that update the
> docs at the same time as they change the product -- reviewers should check
> for this when reviewing any PR that affects a public API, config setting,
> etc. We also cut the support branch well in advance of planned release
> date and limit changes on the support branch to critical fixes only.
> Whenever necessary, anyone should feel free to file blocker tickets for
> missing/incorrect docs to ensure the release does not ship prematurely
> without meeting Geode’s standard of documentation.
> [1] https://geode.apache.org/docs/
>
> From: Dave Barnes <db...@apache.org>
> Date: Tuesday, June 14, 2022 at 3:11 PM
> To: jblum@vmware.com.invalid <jb...@vmware.com.INVALID>
> Cc: dev@geode.apache.org <de...@geode.apache.org>
> Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> John,
> Thanks for acknowledging that docs are just as important as code! As a
> career tech-writer, the "docs=code" model appeals to me.
> I get what you're saying, and have worked in environments where release
> managers have enforced such constraints.
> In this vein, the Geode code is well-supplied with embedded Javadoc
> comments that behave exactly as you describe, providing a reference that is
> updated as the code is updated.
> The difference with a user guide (as opposed to reference material), is
> that examples and usage guidelines can be finalized only AFTER the code,
> with all its version numbers, naming conventions, etc, are in place.
> Delaying code freeze until docs are complete, in my experience, engenders
> feature-creep and introduces delays, often resulting in compromises that
> allow the release to go out with mis-matched docs. IMO, a separate
> user-guide repo promotes a better and more timely match-up between the
> software and the user guide.
>
>
> On Tue, Jun 14, 2022 at 1:15 PM John Blum <jb...@vmware.com.invalid>
> wrote:
>
> > Personally, I believe doc is a critical component to any software
> project,
> > especially a project like Apache Geode, and so, is the project really
> > “complete “(or should thee codebase really be frozen during a release)
> if
> > the doc is not done or consistent yet?
> >
> > Having the doc be part of the source allows the doc to be (theoretically)
> > in-sync with the codebase as it evolves, as it should be. On the other
> > hand, with a separate repo, it does allow corrections or other
> alterations
> > to be made at the risk of growing inconsistency, which is a huge
> impediment
> > IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> > interfaces).
> >
> > Ideally, I don’t see code and doc being separate or even fundamentally
> > different.
> >
> > This sounds more like a process problem and a workaround to a broken
> > process, to me.
> >
> > $0.02
> > -John
> >
> >
> > From: Dave Barnes <db...@apache.org>
> > Date: Tuesday, June 14, 2022 at 12:15 PM
> > To: dev@geode.apache.org <de...@geode.apache.org>
> > Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> > ⚠ External Email
> >
> > I'd like to move the doc sources for the Geode User Guide from the code
> > repo (
> >
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Conichols%40vmware.com%7C90f35f9a69e9429c221c08da4e52c542%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908414805059869%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=w%2FOjA9CKepainPMniHOjz0kJ5TZE7VCFOetwcIojwsE%3D&reserved=0
> )
> > to a separate geode-docs repo.
> >
> > The primary reason is to allow docs to cycle at their own rate, rather
> than
> > in lock-step with the code. The present arrangement causes problems
> during
> > releases, when code is frozen (including doc sources) to prepare a
> release
> > candidate. This is exactly the time when critical last-minute doc changes
> > are needed, but such changes are forbidden due to the code freeze.
> >
> > I have participated in the Geode project since its inception, and can
> > confidently state that this conflict arises with nearly every Geode
> > release. Setting up the docs in a separate repo would alleviate this
> > regularly-recurring, counter-intuitive situation.
> >
> > Of note: The docs directories and toolset are almost entirely independent
> > of directories and tools needed for code development and release, so
> > removal of the doc sources from the Geode code repo should be painless
> for
> > developers.
> >
> > Observations and opinions welcome...
> >
> > Dave Barnes
> >
> > ________________________________
> >
> > ⚠ External Email: This email originated from outside of the organization.
> > Do not click links or open attachments unless you recognize the sender.
> >
>
> ________________________________
>
> ⚠ External Email: This email originated from outside of the organization.
> Do not click links or open attachments unless you recognize the sender.
>
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Dave Barnes <db...@apache.org>.
Adopting a policy that allows changes to doc sources after code freeze
would address my primary complaint about the present system.
Updating the User Guide at the time a user-visible code change is
implemented is a helpful step toward keeping the docs up-to-date with the
code, but is not sufficient.
Above and beyond individual enhancements, the user guide addresses topics
such as system configuration, upgrades, and the like. Such higher-level
topics are often modified asynchronously from code releases, as are typo
and format repairs. For such asynchronous updates, the fact that the doc
sources are located in the source repo is of little consequence. In fact,
separate repos would allow separate revision histories, an advantage to
both.
One more consideration is the possibility of breaking the monolithic user
guide into smaller separate publications, such as an installation guide,
system management/administration guide, developer's guide, advanced topics,
etc. A change like this would be easier if it started from a docs-only repo.
Did any of those thoughts change anyone's mind?
On Wed, Jun 15, 2022 at 12:29 AM Owen Nichols <on...@vmware.com.invalid>
wrote:
> The Geode project comprises several repos already, include geode,
> geode-examples, geode-benchmarks, geode-native, and geode-kafka-connector,
> and geode-site, so it’s not unreasonable to add another. However, we still
> release all at the same time, so any “code freeze” applies equally to all
> geode repos.
>
> Conceptually, “code freeze” applies to *code we ship*. Test-only or
> docs-only commits are welcome anytime. Actually, any commits are welcome at
> any time -- “freeze” just means the branch is tagged at the point in time
> the release manager creates RC1; any commits after that tag will simply
> become part of a future release (in the event we go to RC2, post-freeze
> commits may or may not be pulled into the current release, at the release
> manager’s discretion).
>
> Although the User Guide source files are currently part of the Geode
> source release, most users probably find the published website [1] more
> convenient. In my opinion, it should be fine to publish improvements to
> the doc site post-release (taking care to exclude commits related to
> unreleased new features, if any)...would that resolve the issue?
>
> > examples and usage guidelines can be finalized only AFTER the code, with
> all its version numbers, naming conventions, etc, are in place.
> Chasing a moving target is definitely be frustrating; luckily there are
> things we can all do to minimize it. I’ve seen many PRs that update the
> docs at the same time as they change the product -- reviewers should check
> for this when reviewing any PR that affects a public API, config setting,
> etc. We also cut the support branch well in advance of planned release
> date and limit changes on the support branch to critical fixes only.
> Whenever necessary, anyone should feel free to file blocker tickets for
> missing/incorrect docs to ensure the release does not ship prematurely
> without meeting Geode’s standard of documentation.
> [1] https://geode.apache.org/docs/
>
> From: Dave Barnes <db...@apache.org>
> Date: Tuesday, June 14, 2022 at 3:11 PM
> To: jblum@vmware.com.invalid <jb...@vmware.com.INVALID>
> Cc: dev@geode.apache.org <de...@geode.apache.org>
> Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> John,
> Thanks for acknowledging that docs are just as important as code! As a
> career tech-writer, the "docs=code" model appeals to me.
> I get what you're saying, and have worked in environments where release
> managers have enforced such constraints.
> In this vein, the Geode code is well-supplied with embedded Javadoc
> comments that behave exactly as you describe, providing a reference that is
> updated as the code is updated.
> The difference with a user guide (as opposed to reference material), is
> that examples and usage guidelines can be finalized only AFTER the code,
> with all its version numbers, naming conventions, etc, are in place.
> Delaying code freeze until docs are complete, in my experience, engenders
> feature-creep and introduces delays, often resulting in compromises that
> allow the release to go out with mis-matched docs. IMO, a separate
> user-guide repo promotes a better and more timely match-up between the
> software and the user guide.
>
>
> On Tue, Jun 14, 2022 at 1:15 PM John Blum <jb...@vmware.com.invalid>
> wrote:
>
> > Personally, I believe doc is a critical component to any software
> project,
> > especially a project like Apache Geode, and so, is the project really
> > “complete “(or should thee codebase really be frozen during a release)
> if
> > the doc is not done or consistent yet?
> >
> > Having the doc be part of the source allows the doc to be (theoretically)
> > in-sync with the codebase as it evolves, as it should be. On the other
> > hand, with a separate repo, it does allow corrections or other
> alterations
> > to be made at the risk of growing inconsistency, which is a huge
> impediment
> > IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> > interfaces).
> >
> > Ideally, I don’t see code and doc being separate or even fundamentally
> > different.
> >
> > This sounds more like a process problem and a workaround to a broken
> > process, to me.
> >
> > $0.02
> > -John
> >
> >
> > From: Dave Barnes <db...@apache.org>
> > Date: Tuesday, June 14, 2022 at 12:15 PM
> > To: dev@geode.apache.org <de...@geode.apache.org>
> > Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> > ⚠ External Email
> >
> > I'd like to move the doc sources for the Geode User Guide from the code
> > repo (
> >
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Conichols%40vmware.com%7C90f35f9a69e9429c221c08da4e52c542%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908414805059869%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=w%2FOjA9CKepainPMniHOjz0kJ5TZE7VCFOetwcIojwsE%3D&reserved=0
> )
> > to a separate geode-docs repo.
> >
> > The primary reason is to allow docs to cycle at their own rate, rather
> than
> > in lock-step with the code. The present arrangement causes problems
> during
> > releases, when code is frozen (including doc sources) to prepare a
> release
> > candidate. This is exactly the time when critical last-minute doc changes
> > are needed, but such changes are forbidden due to the code freeze.
> >
> > I have participated in the Geode project since its inception, and can
> > confidently state that this conflict arises with nearly every Geode
> > release. Setting up the docs in a separate repo would alleviate this
> > regularly-recurring, counter-intuitive situation.
> >
> > Of note: The docs directories and toolset are almost entirely independent
> > of directories and tools needed for code development and release, so
> > removal of the doc sources from the Geode code repo should be painless
> for
> > developers.
> >
> > Observations and opinions welcome...
> >
> > Dave Barnes
> >
> > ________________________________
> >
> > ⚠ External Email: This email originated from outside of the organization.
> > Do not click links or open attachments unless you recognize the sender.
> >
>
> ________________________________
>
> ⚠ External Email: This email originated from outside of the organization.
> Do not click links or open attachments unless you recognize the sender.
>
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Owen Nichols <on...@vmware.com.INVALID>.
The Geode project comprises several repos already, include geode, geode-examples, geode-benchmarks, geode-native, and geode-kafka-connector, and geode-site, so it’s not unreasonable to add another. However, we still release all at the same time, so any “code freeze” applies equally to all geode repos.
Conceptually, “code freeze” applies to *code we ship*. Test-only or docs-only commits are welcome anytime. Actually, any commits are welcome at any time -- “freeze” just means the branch is tagged at the point in time the release manager creates RC1; any commits after that tag will simply become part of a future release (in the event we go to RC2, post-freeze commits may or may not be pulled into the current release, at the release manager’s discretion).
Although the User Guide source files are currently part of the Geode source release, most users probably find the published website [1] more convenient. In my opinion, it should be fine to publish improvements to the doc site post-release (taking care to exclude commits related to unreleased new features, if any)...would that resolve the issue?
> examples and usage guidelines can be finalized only AFTER the code, with all its version numbers, naming conventions, etc, are in place.
Chasing a moving target is definitely be frustrating; luckily there are things we can all do to minimize it. I’ve seen many PRs that update the docs at the same time as they change the product -- reviewers should check for this when reviewing any PR that affects a public API, config setting, etc. We also cut the support branch well in advance of planned release date and limit changes on the support branch to critical fixes only. Whenever necessary, anyone should feel free to file blocker tickets for missing/incorrect docs to ensure the release does not ship prematurely without meeting Geode’s standard of documentation.
[1] https://geode.apache.org/docs/
From: Dave Barnes <db...@apache.org>
Date: Tuesday, June 14, 2022 at 3:11 PM
To: jblum@vmware.com.invalid <jb...@vmware.com.INVALID>
Cc: dev@geode.apache.org <de...@geode.apache.org>
Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
⚠ External Email
John,
Thanks for acknowledging that docs are just as important as code! As a
career tech-writer, the "docs=code" model appeals to me.
I get what you're saying, and have worked in environments where release
managers have enforced such constraints.
In this vein, the Geode code is well-supplied with embedded Javadoc
comments that behave exactly as you describe, providing a reference that is
updated as the code is updated.
The difference with a user guide (as opposed to reference material), is
that examples and usage guidelines can be finalized only AFTER the code,
with all its version numbers, naming conventions, etc, are in place.
Delaying code freeze until docs are complete, in my experience, engenders
feature-creep and introduces delays, often resulting in compromises that
allow the release to go out with mis-matched docs. IMO, a separate
user-guide repo promotes a better and more timely match-up between the
software and the user guide.
On Tue, Jun 14, 2022 at 1:15 PM John Blum <jb...@vmware.com.invalid> wrote:
> Personally, I believe doc is a critical component to any software project,
> especially a project like Apache Geode, and so, is the project really
> “complete “(or should thee codebase really be frozen during a release) if
> the doc is not done or consistent yet?
>
> Having the doc be part of the source allows the doc to be (theoretically)
> in-sync with the codebase as it evolves, as it should be. On the other
> hand, with a separate repo, it does allow corrections or other alterations
> to be made at the risk of growing inconsistency, which is a huge impediment
> IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> interfaces).
>
> Ideally, I don’t see code and doc being separate or even fundamentally
> different.
>
> This sounds more like a process problem and a workaround to a broken
> process, to me.
>
> $0.02
> -John
>
>
> From: Dave Barnes <db...@apache.org>
> Date: Tuesday, June 14, 2022 at 12:15 PM
> To: dev@geode.apache.org <de...@geode.apache.org>
> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Conichols%40vmware.com%7C90f35f9a69e9429c221c08da4e52c542%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908414805059869%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=w%2FOjA9CKepainPMniHOjz0kJ5TZE7VCFOetwcIojwsE%3D&reserved=0)
> to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
>
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
>
> Observations and opinions welcome...
>
> Dave Barnes
>
> ________________________________
>
> ⚠ External Email: This email originated from outside of the organization.
> Do not click links or open attachments unless you recognize the sender.
>
________________________________
⚠ External Email: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender.
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Dave Barnes <db...@apache.org>.
John,
Thanks for acknowledging that docs are just as important as code! As a
career tech-writer, the "docs=code" model appeals to me.
I get what you're saying, and have worked in environments where release
managers have enforced such constraints.
In this vein, the Geode code is well-supplied with embedded Javadoc
comments that behave exactly as you describe, providing a reference that is
updated as the code is updated.
The difference with a user guide (as opposed to reference material), is
that examples and usage guidelines can be finalized only AFTER the code,
with all its version numbers, naming conventions, etc, are in place.
Delaying code freeze until docs are complete, in my experience, engenders
feature-creep and introduces delays, often resulting in compromises that
allow the release to go out with mis-matched docs. IMO, a separate
user-guide repo promotes a better and more timely match-up between the
software and the user guide.
On Tue, Jun 14, 2022 at 1:15 PM John Blum <jb...@vmware.com.invalid> wrote:
> Personally, I believe doc is a critical component to any software project,
> especially a project like Apache Geode, and so, is the project really
> “complete “(or should thee codebase really be frozen during a release) if
> the doc is not done or consistent yet?
>
> Having the doc be part of the source allows the doc to be (theoretically)
> in-sync with the codebase as it evolves, as it should be. On the other
> hand, with a separate repo, it does allow corrections or other alterations
> to be made at the risk of growing inconsistency, which is a huge impediment
> IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> interfaces).
>
> Ideally, I don’t see code and doc being separate or even fundamentally
> different.
>
> This sounds more like a process problem and a workaround to a broken
> process, to me.
>
> $0.02
> -John
>
>
> From: Dave Barnes <db...@apache.org>
> Date: Tuesday, June 14, 2022 at 12:15 PM
> To: dev@geode.apache.org <de...@geode.apache.org>
> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjblum%40vmware.com%7Cb6ae14ef841e416fb22208da4e3a2bb4%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908308999514633%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=vWegMzha9uIc8JMMAYhgxU20V9beAoSbAFOK5aORAfc%3D&reserved=0)
> to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
>
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
>
> Observations and opinions welcome...
>
> Dave Barnes
>
> ________________________________
>
> ⚠ External Email: This email originated from outside of the organization.
> Do not click links or open attachments unless you recognize the sender.
>
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by John Blum <jb...@vmware.com.INVALID>.
Personally, I believe doc is a critical component to any software project, especially a project like Apache Geode, and so, is the project really “complete “(or should thee codebase really be frozen during a release) if the doc is not done or consistent yet?
Having the doc be part of the source allows the doc to be (theoretically) in-sync with the codebase as it evolves, as it should be. On the other hand, with a separate repo, it does allow corrections or other alterations to be made at the risk of growing inconsistency, which is a huge impediment IMO. In Asciidoc, doc can even be based on the source in part (e.g. interfaces).
Ideally, I don’t see code and doc being separate or even fundamentally different.
This sounds more like a process problem and a workaround to a broken process, to me.
$0.02
-John
From: Dave Barnes <db...@apache.org>
Date: Tuesday, June 14, 2022 at 12:15 PM
To: dev@geode.apache.org <de...@geode.apache.org>
Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
⚠ External Email
I'd like to move the doc sources for the Geode User Guide from the code
repo (https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjblum%40vmware.com%7Cb6ae14ef841e416fb22208da4e3a2bb4%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908308999514633%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=vWegMzha9uIc8JMMAYhgxU20V9beAoSbAFOK5aORAfc%3D&reserved=0) to a separate geode-docs repo.
The primary reason is to allow docs to cycle at their own rate, rather than
in lock-step with the code. The present arrangement causes problems during
releases, when code is frozen (including doc sources) to prepare a release
candidate. This is exactly the time when critical last-minute doc changes
are needed, but such changes are forbidden due to the code freeze.
I have participated in the Geode project since its inception, and can
confidently state that this conflict arises with nearly every Geode
release. Setting up the docs in a separate repo would alleviate this
regularly-recurring, counter-intuitive situation.
Of note: The docs directories and toolset are almost entirely independent
of directories and tools needed for code development and release, so
removal of the doc sources from the Geode code repo should be painless for
developers.
Observations and opinions welcome...
Dave Barnes
________________________________
⚠ External Email: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender.
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Dave Barnes <db...@apache.org>.
I think the committer list, like the PMC membership, is shared across all
the Geode-related sites. The geode-docs site would be added to this list.
From the "Committers" link on Geode "Community" page (
https://geode.apache.org/community/):
Repositories managed by this Committee (from ASF Git mirrors
<https://git.apache.org/>):
- geode: https://gitbox.apache.org/repos/asf/geode.git
- geode-benchmarks:
https://gitbox.apache.org/repos/asf/geode-benchmarks.git
- geode-dotnet-core-client:
https://gitbox.apache.org/repos/asf/geode-dotnet-core-client.git
- geode-examples: https://gitbox.apache.org/repos/asf/geode-examples.git
- geode-kafka-connector:
https://gitbox.apache.org/repos/asf/geode-kafka-connector.git
- geode-native: https://gitbox.apache.org/repos/asf/geode-native.git
- geode-site: https://gitbox.apache.org/repos/asf/geode-site.git
- geode-svn: https://svn.apache.org/repos/asf/geode/
On Thu, Jun 16, 2022 at 6:08 AM Joris Melchior <jm...@vmware.com.invalid>
wrote:
> I like this idea. I agree that changes to documentation are different from
> changes to code, and documentation should be able to move in a different
> cadence.
>
> Would committers to Geode and Geode-docs be the same after this proposed
> change?
>
> Joris Melchior
>
> From: Dave Barnes <db...@apache.org>
> Date: Tuesday, June 14, 2022 at 3:14 PM
> To: dev@geode.apache.org <de...@geode.apache.org>
> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjmelchior%40vmware.com%7C54eb53d60ca94a1b157308da4e3a1593%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908308627227614%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=2JRX3rpAptf1Sa0EmEPJnDu%2B3mS%2FsEB83M2warTTni4%3D&reserved=0)
> to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
>
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
>
> Observations and opinions welcome...
>
> Dave Barnes
>
> ________________________________
>
> ⚠ External Email: This email originated from outside of the organization.
> Do not click links or open attachments unless you recognize the sender.
>
Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
Posted by Joris Melchior <jm...@vmware.com.INVALID>.
I like this idea. I agree that changes to documentation are different from changes to code, and documentation should be able to move in a different cadence.
Would committers to Geode and Geode-docs be the same after this proposed change?
Joris Melchior
From: Dave Barnes <db...@apache.org>
Date: Tuesday, June 14, 2022 at 3:14 PM
To: dev@geode.apache.org <de...@geode.apache.org>
Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
⚠ External Email
I'd like to move the doc sources for the Geode User Guide from the code
repo (https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjmelchior%40vmware.com%7C54eb53d60ca94a1b157308da4e3a1593%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908308627227614%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=2JRX3rpAptf1Sa0EmEPJnDu%2B3mS%2FsEB83M2warTTni4%3D&reserved=0) to a separate geode-docs repo.
The primary reason is to allow docs to cycle at their own rate, rather than
in lock-step with the code. The present arrangement causes problems during
releases, when code is frozen (including doc sources) to prepare a release
candidate. This is exactly the time when critical last-minute doc changes
are needed, but such changes are forbidden due to the code freeze.
I have participated in the Geode project since its inception, and can
confidently state that this conflict arises with nearly every Geode
release. Setting up the docs in a separate repo would alleviate this
regularly-recurring, counter-intuitive situation.
Of note: The docs directories and toolset are almost entirely independent
of directories and tools needed for code development and release, so
removal of the doc sources from the Geode code repo should be painless for
developers.
Observations and opinions welcome...
Dave Barnes
________________________________
⚠ External Email: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender.