Address build-up of stale branches

[Igor Velikorossov (RussKie)]

Dear Maintainers,
Please disable the default "merge" strategy and replace it with the "squash merge" strategy to make the repo history cleaner and easier to navigate.

No one really cares how many times a contributor had to perform tracking merges of the base branch or address feedback; what matters is the end result.

Thank you

[Mike Harder (mikeharder)]

Igor Velikorossov (@RussKie): In which branch are you seeing this? We do require squash merges to branches like main for just this reason.

From your screenshot, you might be looking at a branch like RPSaaSMaster, where we need to use merge commits to stay in sync with main.

[Igor Velikorossov (RussKie)]

Yes, I'm looking at RPSaaSMaster. It's really overwhelming and mentally taxing for a contributor.

Please also consider pruning all dead branches - there are thousands of those, which again is mentally taxing and consumes network bandwidth and local storage.

There are also branches with extremely similar names, which lead to utter confusion - e.g., it took me good 5 minutes to figure out the "right" branch:

[Mike Harder (mikeharder)]

Thanks for the feedback, but these were all known issues, and to be frank I don't think we can fix any of these.

I don't think we can change how main merges to RPSaaSMaster, without causing even bigger problems. My recommendation would be to use the history in public/main instead of private/RPSaaSMaster when possible, since it should be much cleaner.

Stale branches we could clean up, but it's never been a priority, and the risk of accidentally deleting an active branch outweighs the cost of keeping the branches in the repo. You can limit the branches you clone locally.

For branches "rpaasmaster" and "rpsaasmaster". Current permissions model is anyone can push any branch with any name, so even if we delete these branches, anyone can push them again. So I don't think there's a solution other than "choose your target branch carefully".

[Igor Velikorossov (RussKie)]

I have some experience in managing large and popular git repos, and I respectfully disagree.

There are several fixes that can help addressing the build-up of stale branches. One option is to switch away from "trunk"-based model to the fork model - this will substantially reduce the "noise". This is the model set in many dotnet/* repos.

GHCP provides some other solutions. For example:

---

Option 1: Enable auto-delete on the repository

In Settings → General → Pull Requests, enable "Automatically delete head branches". This will prevent future stale branches from accumulating after PRs are merged.

Option 2: Script-based bulk deletion

Use the GitHub CLI to delete stale branches in bulk:

⚠️ WARNING: Review the list before deleting!

# List all branches with their last commit date, filter old ones

# First, list all unprotected branches
gh api repos/Azure/azure-rest-api-specs-pr/branches --paginate \
  --jq '.[] | select(.protected == false) | .name' > branches.txt

# For each branch, check if it was a head branch of a merged PR
while read branch; do
  # Check for merged PRs using this branch
  result=$(gh api "repos/Azure/azure-rest-api-specs-pr/pulls?head=Azure:${branch}&state=closed" \
    --jq '[.[] | select(.merged_at != null)] | length')
  if [ "$result" -gt "0" ]; then
    echo "Can delete: $branch"
    # Uncomment the next line to actually delete:
    # gh api -X DELETE "repos/Azure/azure-rest-api-specs-pr/git/refs/heads/${branch}"
  fi
done < branches.txt

[Mike Harder (mikeharder)]

Thanks for these suggestions to help manage the stale branches. I agree this is one area we can make at least some improvement, while still being fairly conservative. For example, we could backup the branches to another fork before deleting.

1. Regarding forks, this repo allows opening PRs from forks (and I think some docs recommend it), but doesn't require them. The repo has been configured this way for years, and changing it now to require forks may be disruptive to existing workflows. Particularly, if users need to make a small change to a spec one time, they may prefer to create a lightweight branch in the main fork, rather than creating their own fork. So this is a fair suggestion, but it would require considerable thought and consensus-building before it could be implemented, and then might require changing many other workflows that rely on creating branches.

2. Both public and private repos currently set Automatically delete head branches: true, and it's been this way for at least the last several months, maybe years. I don't remember a time when this wasn't set, but if there are a lot of stale branches, it probably wasn't set for those branches.

3. Only deleting branches from merged PRs is a good idea, we will consider this. [EngSys] Cleanup stale branches from merged PRs #41454

[Mike Harder (mikeharder)]

Wes Haggard (@weshaggard): Do you have any thoughts about possibly changing the repo config to require opening PRs from forks (at least for most users, maybe allow admins to create branches).

I have long considered whether this might be better, to prevent the stale branches. But I know it's a disruptive change to make now, after being allowed for so many years. I'm not sure if there are any specific requirements for users to create branches instead of using their own forks, or it's more a preference of enough users where it's worth the cost of stale branches.

Another factor in favor of allowing branch creation, at least currently, is the GitHub Copilot Coding Agent can only create or append to PRs from branches, not forks. And we certainly don't want to block Copilot usage in the repo.

Finally, I'm not sure it's even technically possible to prevent branch creation, with the current model we use for collaborator/write permissions.

[Igor Velikorossov (RussKie)]

Repo maintainers with "write" access will still be able to create branches, the same goes for the approved bots.

Enforcing fork-only model is disrupting, I agree, though may be GitHub now provides some additional controls.

At the same time, there are 1.4K open pull-requests in the repo, realistically how many of those PRs are active and how many abandoned (i.e., haven't had any activity in the past 30/60/90 days) and aren't getting merged? It could be worth entertaining these questions and weighing up whether it's worth biting a bullet and get all active contributors to fork the repo and resubmit their PRs.

[Wes Haggard (weshaggard)]

I agree that we have way too many branches and open PRs and it would be nice to do some clean-up but it just hasn't been very high on the priority list compared to other work. As for your suggestions we always have auto-delete of head branches and we even have branch clean-up automation, but we haven't done a concerted effort in getting to a better state after we took ownership a few years ago. I don't think there is a good way to force things to come from a fork and I'm not sure I want to enforce that here given the nature of our mono repos.

We have bots that will mark old PRs for closing and close them after some time, but we haven't turned that on in this repo yet because we just haven't spent the effort on it yet. I also think we can clean-up branches in public and private that haven't been touched in years. I would be supportive of doing both of those but again it just boils down the priority which is relatively low.

As for the rpsaasmaster duplicate branches I agree it is confusing and I've just deleted the duplicates and have done it in the past as well. The way to identify is to look for the protected branch but I know that is also not ideal. Due to the nature of branch case-sensitivity I don't know if there is a good way to block those other branches, but I do agree the casing here is confusing and we would have been better off all lowercase but that was created way before we owned this repo.

[Igor Velikorossov (RussKie)]

Wes Haggard (@weshaggard) Mike Harder (@mikeharder) I'm getting the following error now:

"C:\Program Files\Git\bin\git.exe" -c fetch.parallel=0 -c submodule.fetchjobs=0 fe
 "--all" --prune --force                                                          
From https://github.com/Azure/azure-rest-api-specs-pr                             
 * [new branch]              RPSaaSDev  -> origin/RPSaaSDev                       
 * [new branch]              RPSaasDev  -> origin/RPSaasDev                       
error: You're on a case-insensitive filesystem, and the remote you are            
trying to fetch from has references that only differ in casing. It                
is impossible to store such references with the 'files' backend. You              
can either accept this as-is, in which case you won't be able to                  
store all remote references on disk. Or you can alternatively                     
migrate your repository to use the 'reftable' backend with the                    
following command:                                                                
                                                                                  
    git refs migrate --ref-format=reftable                                        
                                                                                  
Please keep in mind that not all implementations of Git support this              
new format yet. So if you use tools other than Git to access this                 
repository it may not be an option to migrate to reftables.                       
                                                                                  
Done                                                                              

RPSaaSDev and RPSaasDev are different in Linux but the same on Windows.

[Mike Harder (mikeharder)]

We could try to clean these up as we find them. But I don't believe we can prevent users from creating branches that differ only in case, so any fix would be temporary. I think this is a problem you can only solve reliably on your client.

[Igor Velikorossov (RussKie)]

Yes, you can :)

Git hooks are there to help enforcing all kinds of rules (including casing or naming conventions).

[Wes Haggard (weshaggard)]

Git hooks are historically not a reliable way to enforce anything because they must always be installed and reliable on every git clone. It would be nice if this was a feature github provided but as far as we know it isn't so there isn't a great way to enforce this.

[Igor Velikorossov (RussKie)]

FWIW, multiple internal repos use hooks.

[Wes Haggard (weshaggard)]

We are mostly open-source and we have tried them on many different occasions and they always end up getting disabled because they aren't reliable and so they cannot be depended upon.