I'm fully in favor of part 1, +1 On the docs, I'd say a slightly hesitant +1 as is, given the situation Jan describes. I still think it would be an improvement to merge the repo since PRs which correctly update couchdb+docs would more likely keep changes and their docs together. Aside from direct docs synchronization for updates to functionality in couchdb's main repo, I think this combining helps with keeping an update to any dependency version in rebar with its changes to couchdb/docs, which could reduce accidentally missing new visible functionality when updating dependencies of older branches for bug fixes.
I would like to suggest that we explore options with automation to try to help remember all doc changes for a PR. I.e. the checkbox in the PR template can help, but maybe we could also auto-label PRs with "no-doc-changes" to remind reviewers, and/or have triggers for PRs that do and don't touch files under docs? Regards, -Will Am Sa., 4. Juni 2022 um 11:04 Uhr schrieb Jan Lehnardt <j...@apache.org>: > > 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 >
