These repositories all contain a main branch, which can be considered the development branch, and a release branch from which the packages are built. The cherry-pick strategy used today is causing for confusion, which is why I want to start this discussion. Below are some of the main topics I believe we should clarify and are a cause of confusion. Please feel free to add to it or correct me.
Since we only maintain a single branch for a release called v1.0.x, do we really need a main branch and a release branch. For a release we always cherry-pick all commits from main to the release branch. Can’t we consider a single-branch solution from which we do the releases, at least until we see a strict need to branch off to different versions?
From my perspective we can stay on the same branch, do the releases from that branch and only branch off if we really see a need to maintain an old release with an update. I have personally not seen that scenario yet and I don’t see the need for it at all. But in case we need it, I was thinking more something like this:
An approach seen on a lot of Debian packages on Debian Salsa is that release branches just add package building and pipeline logic on top of the git source repository. In that case, the v1.0.x branch would just be used for adding the debian directory and the pipeline logic on top of main to get the packages released. Regularly merging main into the v1.0.x branch. In that case, main would become a source code only branch of which no packages can be built. If this is the route we intend to go, we should do a thorough cleanup of the branches.
We seem to be inconsistent in cherry-picking commits and we even do commits only on release branches that never made it into the main branch. A simple git cherry -v main v1.0.x on a repository gives insights in this. Examples of such commits being:
These are all build related changes, I realize that. But unless we document properly how the branching strategies should work and if it should be possible to build packages from main as well, it is confusing for any developer to work with these branches.
Unfortunately examples of commits never making it into release branches can be found as well:
These examples are just to demonstrate that we have an inconsistent way of working, that feeds into more confusion on how to handle these repositories. I think it also shows we have quite some space for human error in our current processes.
What I would like to get out of this discussion is:
Clarity on how the branching was intended from the start and how we will continue from here.
Create a clear documentation on our branching strategies. Clarify to developers and contributors how these repositories can be worked with.
@chuck maybe you have some background and an opinion on the above, since you have been working with this for a long time. It would be valuable to get your feedback on the above.
When we first figuring out the release process for the distro to order projects (rucksack, pasha, etc) we decided to follow the linux kernel method of releasing stable kernels. That is all the development work goes into a “main” branch and there would be periodic releases of these new features to a “stable” branch. Obviously this kind of didnt happen at least the periodic releases bit, because we release the Debian packages only when we are close to release for elxr. Or due to our open development methods that a developer cuts a release when they need something. So to answer your questions:
We tried to follow the stable kernel process where development is done in the “main” branch and there is cherry-picks between the two branches with the proper policy. However, we have not documented this process nor strictly followed this process because of one thing or another. I would love to have a proper release process with a proper release manager/maintainer and have some automation between the two branches. Usually my thinking is most things is try to keep things as simple as possible.
As you know there are many ways to package a piece of software for Debian especially with git. The process that we chose to debianize the python packages for distro to order was basically chosen mostly due to the limited bandwidth I had at the time and what other stuff that needed to be done. I am open to looking at other ways of maintaining the git repos but keeping things simple is still the goal. Which is not documented as well.
The cherry-picking and what is done in the release branches is very inconsistent due what should be documented and what actually happens during a release cycle in For example, we use the elxr-config manifests for creating release artifacts for elxr, which in my opinon should be split out from distro to order. Again stuff like this is not documented.
I guess my follow up question do we have a wiki for documenting this kind of stuff yet?
Thanks for the explanation and background on the branching.
Since we seem to agree that the best solution is to keep things simple, my proposal would be to keep a single branch and only branch off where really needed. Since we always backport everything from main to the release branch today, I think this is the easiest solution to prevent from merging and cherry-picking.
As much as I like the stable kernel release methodology and branching strategy, for me it feels too complex for our scenario. We do not have long-term maintenance of our packages today, we do very frequent releases and basically only release a single version into the package repository. I think we can consider such a branching strategy, with long-term support versions, if we see the need for it. But today I do not see the need. I personally prefer adding complexity when needed.
My proposal would be to have:
A single branch for development, for example v1.0.x or just main.
Release from that specific branch once the development is considered ready.
Developers can create merge requests against the release branch.
Make use of the UNRELEASED target distribution in the debian/changelog files to prevent packages to be published and released using shared aptly.
The logic for taking into account UNRELEASED as a target distribution doesn’t exist today, but a proposal has been done here to include this logic.
I think this method also makes more frequent releasing easier if needed, since the process is more lightweight.
Here I am only considering branching strategies for repositories where code is not pulled in from an upstream git repository, but maintained and developed within the same git repository. For repositories where we pull in external code from upstream git repositories, I think we can follow the example way of working that Debian Salsa is using, pulling in the upstream code and adding an additional branch for the debian directory and build logic.
Would this be something that you think would work?
As you guys have pointed out there have been two challenges.
The first being that there has been a push to add features to a release and not stick strictly to bug fixes, this is reflected in the fact that almost every commit is in turn cherry-picked to a release branch. If we stick to a release only getting bug fixes, this should go away.
The second issue is work being done in a release branch and then having to be pulled back into the main branch. Again, enforcement of the rules guiding development need to be applied. Such commits must be pushed to main first. Maintainers using git-cherry will quickly grow tired of this and ensure this is the case.
I still like having a development branch, as this provides the freedom to introduce changes without affecting existing releases. I struggle with how this has been giving us trouble when this is a common workflow throughout most open-source projects.
For me I see several issues here, reflecting on your comments.
I don’t think we have strong enough maintainer push-back today. If we stick to the two branch strategy, merge requests to the release branch should simply be reject by the maintainer, when they instead should go to main. At least for the most part, because I would even claim bug fixes often go to main first. This unfortunately doesn’t always happen, as we have seen.
The documentation describing our way-of-working today is missing, so it is also not very clear to which branch a developer should target the change. We can assume people know, but I don’t think that is a fair assumption to make if you haven’t been working with these projects before. Not every projects uses the Linux kernel branching strategy, there are a lot of projects adopting very different ways of working.
The other issue I see is that there is no real difference today in bug fixing and feature development. The release branch always gets all commits, bug fix or feature. Basically we do continuous integration on two branches in parallel.
I still see it as unnecessary administration today to maintain two branches. Once we have more frozen and stable releases of tools packages, I agree, a branching strategy could be valuable. Right now I see it is causing more confusion than added value.
I like the more pragmatic approach of introducing a branching strategy when there is a need.
This change to a single branch would require that every merge request includes an updated changelog and a new release. Personally I will be hesitant to contribute to a project if this is expected of me for every change. I want the freedom to contribute smaller changes rapidly and have these grouped when a release is planned.