Looking at https://docs.readthedocs.io/en/stable/versions.html, they recognize an explicit "stable" tag or just picks the latest semantic version branch or tag. They use https://peps.python.org/pep-0440/ rules to parse and that allows for a ".postN" suffix for a tag/branch. So we could have a 3.2.2.post1 branch if we don't want to maintain a stable tag. We could even create that branch on demand from a 3.2.2 tag when we have docs updates after 3.2.2 is out.
This would work with either scheme - docs in the main repo or separate as they are now. The idea of keeping them in the main couchdb repo (provided we can sort out the CI so usability of docs-only vs code-only PRs doesn't suffer), would just keep the extra branching and cherry-picking in one repo only. Cheers, -Nick On Sat, Jun 4, 2022 at 5:04 AM Jan Lehnardt <j...@apache.org> wrote: > > 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 >
