Simplifying dev workflow by keeping only `main`?

[leewujung]

Currently we have three primary branches that we work against:

• main: this branch is mostly only merged into at new releases or by bots, except for occasional README updates
• dev: this branch is where the majority of changes are merged to
• stable: this branch is used for pushing new documentation into, and it is set to the default on ReadTheDocs

This flowchart in our docs shows the complexity of this workflow.

@ocefpaf recommended changing this to the more standard pattern where the latest code is merged to main. I think that is a great idea.

I've found that:

• having stable is pretty redundant and causes confusion, because we really should try to tie new features with docs updates, so that the docs are not outdated.
• since right now the full test suites are only run when changes are merged to main, it has happened many times already that there are uncaught bugs in the new changes that I had to scramble to fix right before release
• having dev and only merged to main seems to provide a bit of mental comfort (?) that anything that breaks is in dev but not main, but that does not seem necessary

@lsetiawan @valentina-s : Any thoughts on this? I am thinking this is probably the time to do it.

[lsetiawan]

having stable is pretty redundant and causes confusion, because we really should try to tie new features with docs updates, so that the docs are not outdated.

The stable branch was definitely confusing for me too. I think if a user wanted a specific "stable" documentation they can get it by going directly to that specific version.

since right now the full test suites are only run when changes are merged to main, it has happened many times already that there are uncaught bugs in the new changes that I had to scramble to fix right before release

Yea I think it's time to move forward to the "trunk-based" workflow. Seems like this gitflow workflow is now a legacy workflow: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow, used to be popular 😛

I do agree that it does add a layer of complexity that can be simplified.

[leewujung]

Thanks for chiming in! I think we can do this for v0.8.4 to see it works out. There aren't that many changes, so probably suitable for these background things. I'll plan to set things up and have doc updates ready to go, some time early next week.

@lsetiawan I may need your help on changing the GitHub Action targets to make sure everything is set up correctly, and questions such as: do we still want to push to test pypi at each merge to main?

[lsetiawan]

Action Items:

• [x] Sync up dev with main
• [ ] Check and update necessary CI configurations
• [ ] Check and update RTD branch
• [ ] Check and update pypi branch

[leewujung]

RTD: point "stable" to latest release, "latest" points to main

[leewujung]

For changes going into v0.8.4 we are now merging to main. We'll complete the other steps re github workflow in v0.9.0.