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 <dbar...@apache.org> Date: Wednesday, June 15, 2022 at 8:11 AM 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%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.
