Github flow questions: versioning and handling multiple features

Is there somewhere (in pyopensci or out on the internet) that gives a good explanation of how to do versions in the github flow git workflow? On the git side of things I understand this workflow to mean that (1) there is a main branch, this is production branch, which means that deployed code is going to built from commits on the main branch and (2) feature branches are split off from main and merged back into main when they’re ready (possibly via PR). I don’t think there should be any commits to main other than merges from feature branches.

My questions are about how to handle multiple features and versions (and releases I guess).

  • Should every single merge into main (and therefore every commit on main) get a new version number? I think the answer is yes, but I’ve seen some sources say you could collect a few features on main and then release them together. But I guess my paraphrasing would be consistent with “new version tag on every merge into main, but there doesn’t need to be a release for every single version tag”.
  • Is it possible, then, to have a new version that includes multiple features? Using this workflow I’ve found myself to do something like. Work on a relatively major feature in the code and documentation. But while working on that feature maybe I’ll make minor changes elsewhere in the code (e.g. cleaning something up, fixing documentation typos or improving clarity). The feature branch then ends up actually have a few different features. Is that wrong?

If the answers are: yes, tag every merge into main with a new version and yes, each feature branch should strictly have one feature then that raises questions for me about small changes. What if I have a typo that I want to fix? I could make a new branch, PR and merge it into the code and make a new version. Is it typically to have new versions of code that only differ by, e.g. a single typo like that?

If that is typical then I’m curious to learn more about best practices around change logs for a repository. For bigger projects I’m used to seeing changelogs with many changes for new releases, but in the model described above, the changelog would always be pretty much about one change per version number.

Also, I know this gets related to CI/CD, but I’m interested in answers sans automation. Once I understand what the workflow should be, then I can look into tools to automate that workflow.

What are answers to some of these questions, and where can I learn more?

1 Like