Mismanaged Branches

[asahasrabuddhe]

I just wanted to share something that I have experienced working with this codebase. Currently, the master branch is not aligned with the latest stable release. This is not correct. As per convention, the master branch must always contain production-ready code which in our case is tagged at v1.21.0

We could have another branch say develop where we could first merge PRs and then eventually carve out releases from that branch once we are satisfied.

The major issue here is that people not using Go Modules would get master code which is not yet stable or consistent with our idea of the latest release that we would support and maintain.

If we do make this change, we would have better management of code for ourselves as well as help fix a lot of problems for people not currently using Go Modules.

[coilysiren]

I'm 👍! I think we would just need a some instructions in CONTRIBUTING.md describing how this works.

[coilysiren]

It would also be nice to have an example of a repo that does branches correctly 🙏

[asahasrabuddhe]

@lynncyrin Unfortunately I do not have a repo that perfectly follows the model that I have in mind. However, I can share this: https://nvie.com/posts/a-successful-git-branching-model/

This blog post is the source of inspiration behind my idea. I have already implemented this in couple of repos at work which I am not able to share. I would very much like to have this flow in place here in our projects.

What we would need to do now is follows:

1. Rename current master branch to develop.
2. Create a new branch called master from the current release commit 1.21.0 or 1.22.0
3. Update the CONTRIBUTING.md with new instructions. In short, every branch will be named to indicate the purpose. feature, hotfix, bug, patch etc. All PRs would only be directed to develop branch. And we as maintainers would then choose the PRs and craft out a release branch which would then eventually get merged with the master and we would have a new release.

I don't think we have enough rights to do point 1. We would need @AudriusButkevicius 's help if he is on board. Then we can do point 2 and finally I will update CONTRIBUTING.md with point 3

What do you guys think?

@saschagrunert your opinion would also be needed in this matter.

[AudriusButkevicius]

I somewhat disagree. Master is for development, tags are for versioning. Sure, people without go mod might have some pain, but various different options for addressing this in go have existed for years. If people are not using them, it's their own fault. Go mod is our vendoring system and people should use it.

I'd like to see an example (a go repo) where this is done differently. Even go itself follows the same model.

[asahasrabuddhe]

If not this then I suppose we should at least have dedicated release branches to avoid the mess that I am seeing at the moment.

[AudriusButkevicius]

Why do we need a release branch? We have tags.

[asahasrabuddhe]

We need this because, anyone wanting to contribute is forking the project from master which can have unfinished or unstable features. We could either stabilise the contents in that branch or otherwise request people to fork from elsewhere.

[AudriusButkevicius]

I don't think we should merge unfinished/unstable (unbuildable?) stuff to master.

[coilysiren]

Having sat on this for a day or so - I need to see how another popular repo handles this. Primarily because, as mentioned above, I believe the way we're doing it is the same as how most people are doing it.

[marwan-at-work]

the master branch must always contain production-ready code which in our case is tagged at v1.21.0. We could have another branch say develop where we could first merge PRs and then eventually carve out releases from that branch once we are satisfied.

The master branch, in my experience, is usually the dev branch. You can look at the Go language itself where the master branch is the development branch. The way it works is that the maintainers decide what number of bugs/features go into the master before tagging the next release.

That said, having a release branch is usually very helpful when you want to back-port patch fixes into a release. For example, if you tagged a new release (v1.3.0) a month ago, and since then you have merged new features to master but you're not ready for a release yet but you also found a bug in v1.3.0 that you'd like to fix and release a v1.3.1 patch for. You don't want to merge everything in master. And therefore, a release branch makes sense. The release branch can be either major.minor or major.minor.patch. Go does the first one while a project like Athens does the latter.

The major issue here is that people not using Go Modules would get master code which is not yet stable or consistent with our idea of the latest release that we would support and maintain.

This is not true. Go Modules prioritizes tags over the master branch unless the user explicitly asks for the master branch.

Hope this helps :)

[coilysiren]

My impression is that there's something to do here, but it's not clear what that is. Can someone one creating a guidance document here?

[ryanwilsonperkin]

Hey! I'm not a contributor to this project, but just happened across this issue while evaluating cli. The Django project might be a good example to follow here. They use master as the base branch that in-development work is merged into that is destined for future versions, and stable/major.minor.x branches for branches that are still supported and getting features merged into them. The project has a good track record of patching recent minor versions, and I think could be a good model to follow.

[stale]

This issue or PR has been automatically marked as stale because it has not had recent activity. Please add a comment bumping this if you're still interested in it's resolution! Thanks for your help, please let us know if you need anything else.

[coilysiren]

I'm not sure there's significant momentum behind making a change here, so I'm gonna close this as stale ♻️