Proposal to Change the GitHub Branch Structure [Dev Branches, Test Branches, and Main]

[chadcwilliams]

I am proposing that we consider changing the way that we use GitHub Branches (after this AutoRA release). This partly stems from the fact that EEG-GAN users quite often pull our repo's main branch expecting it to be our latest release but it's in fact our Dev branch, and partly from me chasing down a bug in autora and getting lost in our numerous branches.

There are many ways to organize branches, and this is just one idea as an example. I would assume @hollandjg knows more about this than me. As an example, we have three main branches:

1. Dev Branch: This is the working branch that is allowed to be unstable. When working on a feature or bug, you pull from this branch, implement the change you are making, and then PR back into this branch. In other words, this is where all features and bug fixes are first merged to ensure compatibility.
2. Test Branch: When the Dev branch reaches a stable state with all features for our next release as well as all bugs fixed, we create a PR from Dev to Test. The test branch is then tested across a series of use-cases to ensure it is all, in fact, stable and works well. If issues come up, we fix them on the Dev branch and then a PR back to the test branch. Once the test branch is fully tested, it is ready for a release and then a PR is made to merge it with the main branch.
3. Main: This branch is the latest release. A PR is made only when something is ready for release and then it is merged and released.

[hollandjg]

Hey Chad, thanks for this suggestion!
You bring up an important point – the fact that often the main branch isn't actually the current most stable version, and that causes issues – is something we absolutely should think about.

There's a git workflow called "gitflow" https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow which does the kind of thing you're suggesting. You've got a main "develop" branch where you do most of your work, and then individual "release" branches for different versions of the code. I used it for a few years and it's got some definite benefits, but recently it's fallen out of favor.
Atlassian have a bunch of good documentation on different models – maybe have a look at their site? We currently use the "feature branch workflow".

Another thing to think about is whether we can do releases on every merge to main, on all of our projects. That would mean that if your version of a package is up-to-date, you can clone the repo and you'll get the same code on main.
That would mean being much more structured about how we do pull requests (so that we can automate things), and we may need to do some thinking about how that will affect our documentation.

If there's a particular version of a subpackage (autora-core, autora-theorist-bsr..., find out the version by running pip freeze) someone is having an issue with, then one tip is to navigate to the release tag and look at the code as it was back then:

You can clone that and test things out as they were then, before determining whether the fix is in a newer version or whether the problem still affects the current one. That might be part of the solution.