> 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?
That's an interesting idea, Will. Something like that could work. Add a PR or commit label in Github perhaps? Usually what happens is that the docs PR follows the main code PR. So first the main PR is reviewed / merged, then the contributor would remember to make a separate docs PR. But sometimes (including myself quite often) we forget to do that. That's why I thought keeping it in one pull request would make it a bit easier to not forget and keep both exactly in sync. > Is it possible to distinguish what has been changed in a repository? That could work, Ronny! In a pull request CI job we can check the diff between that pull request and the branch we're merging into (main, 3.x). Then, see if there are any file changes to src/docs/* and trigger or skip various jenkins stages based on that. So if changes are only to docs, just run the docs CI quickly and skip the whole code CI. This would be for pull requests CI only. The full CI, which runs after the merge to main, already runs docs + fauxton + CI builds anyway. Regards, -Nick On Sat, Jun 4, 2022 at 2:07 PM Nick Vatamaniuc <vatam...@gmail.com> wrote: > > 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 > >
