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 <alberto.go...@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 <dbar...@apache.org> > Sent: Wednesday, June 15, 2022 11:06 PM > To: dev@geode.apache.org <dev@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 <onich...@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 <dbar...@apache.org> > > Date: Tuesday, June 14, 2022 at 3:11 PM > > To: jb...@vmware.com.invalid <jb...@vmware.com.INVALID> > > Cc: dev@geode.apache.org <dev@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 <dbar...@apache.org> > > > Date: Tuesday, June 14, 2022 at 12:15 PM > > > To: dev@geode.apache.org <dev@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. > > >
