Heya Nick, thanks for taking my raw idea to the larger group here :)
The one other point that started the whole thing is our publishing of docs. We have a stable and a latest tag where latest just tracks the main branch on the docs repo and stable we move manually when a new release comes out. What does happen though is that after a release, say 3.2.2, we improve the documentation for something that is valid for 3.2.2. If there are no other changes, we can choose to move the stable tag to that commit and get improved documentation as stable for all users online, even though that strictly didn’t exist at the time of the 3.2.2 release. Now, if we first add a new feature in the 3.x line on the couchdb repo and document that in the main branch of the docs repo, and then the docs improvement from before, we can not move the stable tag on the docs repo as that would publish the docs for a not-yet-released feature and the improvement is not available until we release whatever comes after 3.2.2, which might be a considerable time later. My thinking was that it might be neat to follow the branch structure of the couchdb repo in the docs repo, so that we can make this more easily, and from there we got to moving docs into the main repo to avoid double bookkeeping, but that still doesn’t help us in the second scenario outlined above. To make that work we’d need to have a post-release branch for each release that we can merge improvement-only doc commits to and that we can freely move the stable docs tag forward with. It doesn’t matter if we do this on the docs or the couchdb repo with included docs, but it means a little more bookkeeping with branches: - all doc commits go into release branches (main/3.x etc) - improvement-only commits are also merged into a hypothetical 3.x-post-release-doc-commits[1] branch To me this feels like a little overhead for a nice gain, but I’d like to hear from y’all if this is worth it. * * * I’m am +1 on moving 3.x to main and moving main to fdbmain in the couchdb repo. I have no strong opinion on moving docs into the main repo, as that doesn’t solve the problem I’m most interested in, and with adding complexity about CI builds, that might not be worth the hassle, but I’m also not stopping anyone from putting in the work :) [1]: ridiculously long name chosen to avoid getting distracted with bikeshedding. Best Jan — Professional Support for Apache CouchDB: https://neighbourhood.ie/couchdb-support/ *24/7 Observation for your CouchDB Instances: https://opservatory.app > On 2. Jun 2022, at 21:40, Nick Vatamaniuc <vatam...@gmail.com> wrote: > > Hi everyone, > > In a #dev slack thread we were discussing improvements to how we tag > our documentation repo. There were two proposals to simplify the > development and release process, and we wanted to see what the rest of > the community thought about it. Those two ideas are: > > 1. Rename couchdb repo's main branch to fdbmain and rename 3.x to main. > > From an ergonomic point of view, there is more development on the 3.x > branch so having it as main makes more sense. It can help with: > * Issues auto-closing when PRs are merged > * Github code search works better in the default branch > > 2. Move docs to the main repo. > > We noticed that the docs repo tags/branches can get out-of-sync with > the main couchdb repo. We have been merging features in main when they > apply only to 3.2.x and it requires care to keep track of what gets > merged and ported between branches. The idea is to simplify and make > it automatic so docs always follow the main repo so merging and > porting happens in one place only. > > What does everyone think? > > Thanks, > -Nick
