Hi Sammi, thanks for the feedback. I wanted to wait until ZDU wrapped up so I could provide a use case to work through. I agree that rebase will be problematic because it may create commits that individually do not pass CI.
When rebasing, as commits are replayed one by one, conflicts are resolved mostly by manual inspection. Most devs are not checking that every rebased commit builds before moving on to the next one, and they definitely aren't running the full CI suite for each commit. Therefore rebasing means we will likely introduce commits into the history which do not build or pass tests. This can make cherry-picking for patch fix releases dangerous later. At the end of the rebase, the CI is usually checked. Then if it fails, a miscellaneous commit must be added with all the assorted fixes for the rebased commits. Contrasting this with merge, only one new merge commit is created. This can be run through CI and updated as needed until the entire test suite is green on a test branch before adding it to the feature branch. The individual commits before the merge remain untouched so their green CI status is still valid. git show --remerge-diff <merge-commit-hash> will show just the changes applied to the merge commit that did not come from either parent. Here is an example I came across with ZDU: - ZDU added HAProxy and multiple S3 gateways to the upgrade acceptance tests. - Master added a new health check endpoint to S3 gateway and had HAProxy call it in its shared configuration for all tests that use it. - With the merge conflicts resolved everything appeared to build fine, but the upgrade acceptance test failed because HAProxy was configured to query the new health endpoint against the old S3 gateway in the upgrade acceptance test. - We fixed the resolution in the merge commit and re-ran CI, which ensured that all past and present commits remained green in context. Based on this I think we should definitely revisit this feature branch maintenance page. However, I do disagree that it should be left up to branch maintainers. Every other aspect of our version control is standardized such that for each event (commit, release), we know exactly what type of commits, branches, tags and names will be produced. I don't see why feature branches should be given a special pass. Each option has trade offs, but we should definitively decide which trade offs to make. Ethan On Thu, Jul 23, 2026 at 10:50 PM Sammi Chen <[email protected]> wrote: > Ethan, > > Thanks for raising this discussion. > Since we have the new website, moving docs from confluence to the new > website is a good idea. > And in the future, all new documents' first priority location is the new > website too. > > For the detailed feature branch git merge command process, based on my past > experience, I would suggest we leave the option to feature branch > maintainers. > I have maintained a few feature branches since working on HDFS and Ozone. > Initially I use rebase too when the feature is not big, only a dozen > commits. But later when working on big features, the rebase effort became > more and more heavy, then I switched to merge. After experiencing using > both merge and rebase, I favor merge more than rebase now. > But I guess there is someone who may like using rebase more. So it's > better to leave the choice to the feature branch maintainers. > > BTW, apart from STS and ZDU feature branch, object ttl(already merged) , > and short-circuit feature branch is going to merge too. > > Bests, > Sammi > > On Sat, 11 Jul 2026 at 03:17, Ethan Rose <[email protected]> wrote: > > > Hi Ozone devs, > > > > As part of our ongoing documentation updates, I am working on docs for > > feature branch usage which will live under the developer guide on the > > website. This includes: > > - Porting over the completed feature branch merge checklists which lived > in > > confluence > > - Updating our current feature branch merge checklist > > - Adding a guide on feature branch management and merge processes, which > > had never been formally written down. > > > > The last point is especially important since it details the exact way to > > use merge and rebase to incorporate the feature branch into master for > > optimal git history. > > > > The PR is https://github.com/apache/ozone-site/pull/463. It would be > great > > if the community could leave feedback on this PR so that the updated > > practices can go into effect once it is merged. Note that we have STS and > > ZDU feature branches getting ready to merge soon. > > > > Thanks, > > Ethan > > >
