• Created by Unknown User (meonkeys), last updated on Mar 23, 2026 2 minute read

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 12 Next »

Summary

When merging a PR into develop (our main integration branch), use a traditional merge commit instead of squashing, rebasing, and fast-forwarding.

Vote passed.

Status

CLOSED

Who is Involved

Background/Motivation

The original motivation was supporting verifiable signed git commits. This was proposed in 2025  and adopted in 2026. Upon investigation, it was determined the current merge strategy (squash, rebase, fast-forward) precludes signed commits except in special situations (done locally or when squash/rebase were unnecessary, e.g. one commit was created and PR was merged before any other commits on develop were added).

Additional motivations: preserve more history, preserve more developer intent.

When I'm looking at commit history, I want to be able to know exactly what happened, when, by whom, and why. I want to see branch start & end points, when changes were made and unmade. Yes it means more commits. Thankfully Git is built to handle many, many commits. It has excellent filtering to, for example, examine simplified history.

-- Adam Monsen

Goals and Exclusions

Continue to use GitHub for reviewing and merging PRs as well as local tooling (e.g. git merge on the command line).

Encourage developers to use as few or as many commits as they choose in their PRs, with the intent to most clearly communicate the reviewable progress of their work during PR review and for posterity. This means rebasing locally, adding/removing commits, and force-pushing are all still allowed, although these should be used only as necessary/helpful (e.g. when a new commit on develop assists the PR or to correct noise/mistakes). If force-push is used, communicate it thoughtfully.

Encourage developers to leave commits as-is/un-squashed when updating PRs with new changes. It's helpful for posterity / intent forensics to see progress along the way, changes reversed, etc. Ideally with commit log detail about the "why" for the changes, summaries of our discussions leading to the changes, ideas/plans for future changes, etc.

Change Proposed

Standardize on and manually enforce traditional git merge commits for merging approved PRs to the develop branch. When merging a PR, do not enforce squash/rebase/fast-forward.

For examining history, document and practice use of git history simplification strategies such as

git log --first-parent develop
git log --no-merges
git log --max-parents=1

or simply viewing the commits list on github.

After a ~one week bake-in period, enforce new strategy with .asf.yaml:

# must be added to existing github section
# (do not create a new one)
github:
  enabled_merge_buttons:
    merge: true
    squash: false
    rebase: false
  protected_branches:
    develop:
      required_linear_history: false
      required_signatures: true
      required_conversation_resolution: true


Alternatives Considered

Continue to enforce squash/rebase/fast-forward, but do so locally only, so committer's signature is valid. Abandoned as this would leave behind useless merge commit "triangles" in the history.

Phases of work

This is effectively a process change, hence, mostly follows the simple/default FSIP pattern.

  1. DISCUSS
  2. VOTE
  3. TRACK (update community, update docs, remind ourselves via dev list, chat, PR comments)
  4. CLOSE
  • No labels