workflow for documentation updates

[emiliom]

It would be helpful to be able to updates the ReadTheDocs documentation without being tied to code release cycles. Here I'm referring specifically to doc updates that reference the latest released API; in other words, corrections of mistakes, improved explanations, expanded content, etc.

In the Git development-branch (dev) workflow we've adopted for echopype, all changes (code & docs) are merged into dev first, and dev is merged into master only when a new release is ready to be issued. Changes to the API in dev potentially affect the API descriptions in the docs, so they may conflict with the documentation for the current release.

I'd like to propose the following workflow for documentation:

1. Use a docsdev branch that serves as an analog to the dev branch but is used only for doc changes that don't involve changes to the API -- the types of changes listed in the first paragraph. Documentation-only PR's involving such changes would be merged into this branch.
2. When we feel there are "enough" changes in docsdev, we merge into master and prepare a new minor, tagged echopype release that only includes documentation updates. We also merge from docsdev into dev, to keep that branch in sync.
3. To avoid spawning new pypi and conda packages for this minor release, we can tag the release and include a letter at the end of the version; eg, 0.5.1a
4. Use the tag or the letter suffix to ensure that the CI that builds packages is not triggered.
5. At https://echopype.readthedocs.io, change the latest version so it points to the dev branch rather than the master branch. The default version is stable (as it should be, IMHO), which is updated with new releases.

I realize that adopting this workflow adds complexity, for the benefit of being able to push docs updates to live more quickly than the code driven package release cycle allows. I would manage this process. I foresee that at least for a few more months, there is work to be done on the documentation that would benefit from this faster docs release workflow. Maybe by then the benefits of this faster but more complex cycle will no longer outweigh its costs, and we can go back to just the dev > master workflow.

I did some searching on the topic of documentation workflows and couldn't find anything helpful. Some of these suggestions stem from my chat with Jessica Scheick, the maintainer of https://icepyx.readthedocs.io/

Thoughts?

[lsetiawan]

Hmm... this is very complex workflow. I have adapted the readthedocs PR build for the doc-test site since that's what I have access to. Seemed to work for Test PR #379. See docs. I think to simplify this, just keep newest docs update to be PR to dev, and any doc fixes before release to release branch. The PR from release branch to master should also have a PR docs preview now. This way it's clean and not so many different branches to maintain 😄

[emiliom]

Thanks @lsetiawan!! Creating a new RTD "dev" version (https://echopype.readthedocs.io/en/dev/) tied to the dev branch was brilliant.

The part I don't follow is how we'd push doc fixes before new release to the RTD stable version -- the default RTD docs users would see -- w/o also bringing in changes to the API (if there are any):

I think to simplify this, just keep newest docs update to be PR to dev, and any doc fixes before release to release branch. The PR from release branch to master should also have a PR docs preview now. This way it's clean and not so many different branches to maintain 😄

The release branch will include all changes in that release, including potentially changes to the API that would be reflected in the docs build; the latter is what I want to avoid. Plus, we'd still be relying on other branches (a release branch), so it seems like it's not actually reducing the number of branches, but rather using them differently.

Could you elaborate?

[leewujung]

I think we can use what RTD offers re having a custom stable just for the docs, to avoid having to tag not-for-build releases:

We also create a stable version, if your project has any tagged releases. stable will be automatically kept up to date to point at your highest version. If you want a custom stable version, create either a tag or branch in your project with that name.

I actually think what @emiliom is proposing is not super complicated. Assuming we use a stable branch solely for doc updates, then the rules are:

• stable: documentation changes that do not involve actual API and code changes and concerning the LAST release.
• dev: documentation changes that involve any API and code changes and concerning the NEXT release.
• stable needs to be merged into master before dev is merged into master: the merge of dev may require resolving conflicts, but that is actually a good thing that makes sure that our docs are doing a good job on updating things that have changed.

How does this sound?

[lsetiawan]

@leewujung That is great! Thanks for laying it out! 😄 Just one change/clarification:

stable needs to be merged into master before dev is merged into master: the merge of dev may require resolving conflicts, but that is actually a good thing that makes sure that our docs are doing a good job on updating things that have changed.

                                --- dev ----
doc-patches ---                /            \
               \              /              --- release/0.5.x ---
                \            /              /                     \
                 - stable -------- stable --                       \
                /                                                   \
               /                                                     \
            master -------------------------------------------------master

• stable always branches off master after a release. Doc patches go there like you metioned above.
• dev branch goes off from stable after a release.
• release/x.x.x branch gets created from dev to prepare for a release, and this is where we should merge the stable and dev together. This way, master stays clean, since this code is reflecting latest releases.

[leewujung]

dev branch goes off from stable after a release.

I agree with the others but don't understand this one: why wouldn't dev just goes off from master after a release?

[lsetiawan]

I agree with the others but don't understand this one: why wouldn't dev just goes off from master after a release?

Yea. That's fine too, now thinking about it. :)

   doc-patches ---                            
                  \                            
                   \                         
                    - stable ---
                   /            \
                  /              --- release/0.5.x ---  
                 /              /                     \
                /   --- dev ----                       \
               /   /                                    \              
              /   /                                      \
            master -------------------------------------master

Been a while since I did ascii art ... this is too fun 😆

[emiliom]

I've consolidated the descriptions of this workflow, as they stand; noting that we're now describing the entire workflow, not just aspects that are specific to documentation!

Proposed Workflow

• stable branch: documentation changes that do not involve actual API and code changes and concerning the LAST release. The RTD stable version is associated with this branch
• dev branch: documentation changes that involve any API and code changes and concerning the NEXT release. The RTD 'dev` version is associated with this branch
• Preparing for a new release:
  • stable needs to be merged into master before dev is merged into master: the merge of dev may require resolving conflicts, but that is actually a good thing that makes sure that our docs are doing a good job on updating things that have changed.
  • release/x.x.x branch gets created from dev to prepare for a release, and this is where we should merge the stable and dev together. This way, master stays clean, since this code is reflecting latest releases.
• Right after a new release, both stable and dev branch off from master
• A new RTD version is created with each new release
• One thing I'm not sure of: what does the RTD latest version point to? dev branch? If so, is it redundant to have both latest and dev RTD versions?

Notes

IMHO, having a release/x.x.x branch and the workflow around it adds an additional layer of complexity and coordination that I'm not sure is warranted for our small team. It's worth noting this statement in the Gitflow Workflow page: "The Gitflow Workflow defines a strict branching model designed around the project release. This provides a robust framework for managing larger projects."

[lsetiawan]

stable needs to be merged into master before dev is merged into master: the merge of dev may require resolving conflicts, but that is actually a good thing that makes sure that our docs are doing a good job on updating things that have changed.

stable should be merged into release/x.x.x and resolve any conflicts there before releases, not to master.

One thing I'm not sure of: what does the RTD latest version point to? dev branch? If so, is it redundant to have both latest and dev RTD versions?

Right now the dev branch docs are hidden, so maybe this should be latest, in case someone does want to install the latest and greatest from github, since we have stable pointing to stable. One more thing, should dev be the main branch, so that contributors automatically gets put to dev rather than master?

IMHO, having a release/x.x.x branch and the workflow around it adds an additional layer of complexity and coordination that I'm not sure is warranted for our small team.

It does, however, as we speed up development, this provide a way for development to keep moving forward for the next release without affecting the current release that's being tested and worked on such as making last minute bug fixes / documentation update. It is better to get into this habit now, rather than later when we do have a large contribution. 😄

Like for example, If Imran and I were really fast at getting all the 0.5.2 tasks done, and we're both merging right and left to dev, and we are still at 0.5.1, this could be problematic if say you, Emilio is trying to work on catch up on the documentation for just the 0.5.1, and then maybe Wu-Jung has some bug fixes regarding 0.5.1 features. All those would then go into dev and we have like features from 0.5.1 and 0.5.2 ... I mean it could be that, we just release 0.5.1 as all those new features and more, but I think it's better if things are consolidated and in small chunks.

[emiliom]

Thanks @lsetiawan !! For now, I'll comment just on this:

One thing I'm not sure of: what does the RTD latest version point to? dev branch? If so, is it redundant to have both latest and dev RTD versions?

Right now the dev branch docs are hidden, so maybe this should be latest, in case someone does want to install the latest and greatest from github, since we have stable pointing to stable.

I agree. Let's point RTD latest to the dev branch. And then there's no need for the RTD dev version any more, so might as well remove it?

One more thing, should dev be the main branch, so that contributors automatically gets put to dev rather than master?

I've had the same thought. I can see pros and cons. Do you know what's the most common practice in this git workflow? I think I lean towards making dev the default/main

[emiliom]

stable needs to be merged into master before dev is merged into master: the merge of dev may require resolving conflicts, but that is actually a good thing that makes sure that our docs are doing a good job on updating things that have changed.

stable should be merged into release/x.x.x and resolve any conflicts there before releases, not to master.

Thanks for catching that. I now see that my late-night copy and paste job left two statements that were not mutually consistent 🤦. I'll remove the first statement. But, any reason not to merge stable into dev first (instead of into release/x.x.x) before creating the release/x.x.x branch from dev? That way dev is updated with the latest doc updates from stable.

[emiliom]

For a hotfix workflow, see the Hotfix Branches section at https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow

[emiliom]

RTD versions currently set, other than ones corresponding to each release:

• stable: built from stable branch (per RTD rules). This is the default (https://echopype.readthedocs.io/ redirects to https://echopype.readthedocs.io/en/stable/). See https://readthedocs.org/dashboard/echopype/advanced/
• latest: built from master (RTD rules). But shouldn't it point to dev branch, so it's truly based on the latest development (unreleased) code? Having latest based on master branch is not terribly useful, relative to the stable version.
• dev (hidden): built from dev branch by default, based on the version name (dev version is built from dev branch). https://echopype.readthedocs.io/en/dev/ is available but not advertised

[leewujung]

It seems that his issue was closed by #420. @emiliom do you agree or do we still have anything missing?

[emiliom]

Yeah, except for resolving some issues around the dev branch and the RTD dev version. See my previous comment, above, and these comments from @lsetiawan and me. But maybe we should just open a new issue to focus on those decisions alone, and close this old, sprawling and largely resolved issue?

Right now the dev branch docs are hidden, so maybe this should be latest, in case someone does want to install the latest and greatest from github, since we have stable pointing to stable.

I agree. Let's point RTD latest to the dev branch. And then there's no need for the RTD dev version any more, so might as well remove it?

One more thing, should dev be the main branch, so that contributors automatically gets put to dev rather than master?

I've had the same thought. I can see pros and cons. Do you know what's the most common practice in this git workflow? I think I lean towards making dev the default/main

[leewujung]

I agree we should use main (the current master -- let's make the switch after this release) in the same way as the current dev branch. Then there will be only 2 major branches (main for the code and stable for the doc). Since we finished the class-redesign overhaul the development pattern has been pretty clean under the current "PR merge to dev" workflow, so it shouldn't be a big issue to change that to "PR merge to main". @lsetiawan would need to config the CI slightly differently but it should also be straightforward. 🤓

For RTD, how about

• RTD latest points to main
• RTD stable points to stable
  then we can still maintain the flexibility to update documentation independently from the release cycle.

[emiliom]

I agree we should use main (the current master -- let's make the switch after this release) in the same way as the current dev branch. Then there will be only 2 major branches (main for the code and stable for the doc). Since we finished the class-redesign overhaul the development pattern has been pretty clean under the current "PR merge to dev" workflow, so it shouldn't be a big issue to change that to "PR merge to main". @lsetiawan would need to config the CI slightly differently but it should also be straightforward.

We touched on this at our last call. We weren't proposing a change to the workflow. If you're proposing a simplification of the workflow by removing the use of a dev branch, let's discuss -- maybe in a fresh new issue?

For RTD, how about

• RTD latest points to main
• RTD stable points to stable
  then we can still maintain the flexibility to update documentation independently from the release cycle.

Correct me if I'm wrong, but here I think you're building on your previous recommendation to remove the dev branch, right?

[leewujung]

@emiliom: Ha, yes I have mistaken the discussion to be the actual code workflow instead of the RTD! I think there may be advantages to simplify the workflow, but it is not a priority at the moment. Putting it in a separate issue sounds like a good idea so we can revisit later.

[leewujung]

Looping back to this as we move toward the next release (v0.5.5). Is this resolved?

[emiliom]

I've moved the RTD-builds topic to a new, dedicated issue (#467). So, I'm now closing this sprawling issue.