Control advanced Git changes with release-aware decisions

When cherry-pick succeeds but the backport is still not acceptable

main contains a refactor followed by a bugfix. release/1.4 supports an older line, and the bugfix is requested there. The cherry-pick finishes without a conflict, so the Git operation succeeded. Yet a target-line behavior test fails because the bugfix depends on part of the refactor that is absent from release/1.4.

That is the core problem: do not promote command success into release evidence. Your main output is Release-Aware Change Control Record v1. It keeps the source commit, target line, relevant ancestry and prerequisites, transfer or reversal method, behavioral evidence, tag state, version-policy boundary, rollback/reversal limits, residual risk, and human decision in one inspectable record.

The goal is not to choose merge, rebase, or cherry-pick every time. The goal is to explain why a method fits this target and claim, what evidence supports it, and what remains unproven.

Three routes, one acceptance standard

The Foundation route makes source/target, ancestry, and transfer/reversal concepts explicit before the case. The Repair route returns only to the first broken distinction. If you can cherry-pick correctly but treat a clean apply as compatibility proof, the repair focuses on target-line behavioral evidence.

The Experienced / Fast Path compresses syntax, not the artifact or evidence bar. Release-branch experience does not turn a branch name, tag name, merge result, or team intuition into evidence.

Before continuing, answer three questions: what exact source commit is under consideration? What target ref and relevant ancestry are you acting on? If the Git operation succeeds, what independent check could still reject your decision? Without the third answer, the release-aware gate is incomplete.

Mental model: change, history, release markers, and runtime evidence are different

Keep four layers separate:

1. Change content: the patch or logical change you intend to transfer or reverse.
2. History relationship: commits and ancestry on source and target. merge joins histories, rebase reapplies commits on another base, and cherry-pick applies the change introduced by an existing commit in the current context and records a new commit. These are history/change relationships, not a universal ranking of methods.
3. Release marker: a tag can identify an object or commit. It tells you where the ref points; it does not prove an artifact was built, published, or deployed.
4. Behavior/operation evidence: a test, build, or observation bound to the target state.

revert is bounded too: Git records new commits that reverse earlier changes in repository history. If the earlier action changed a database, message, external file, or service, Git alone does not reverse that side effect.

Every conclusion should therefore say which layer it describes and how far its evidence reaches.

Building Release-Aware Change Control Record v1

Build the record from observable state toward a decision:

1. Source: record the source commit and an inspectable locator. A ticket or commit message alone is insufficient.
2. Target: record the target ref, target tip, and relevant ancestry evidence. The name release/1.4 is not itself a compatibility policy.
3. Dependency boundary: state what prerequisite, refactor, API, or behavior assumption the fix relies on and how you checked it.
4. Candidate method: choose merge, rebase, cherry-pick, reconstruction, revert, or another bounded combination with context-specific rationale.
5. Git result: record the operation result without calling it complete acceptance evidence.
6. Target-line verification: run an independent check on the target state and bind the result to that state.
7. Version-policy boundary: use patch/minor/major reasoning only if the project explicitly adopts SemVer and declares a public API. Otherwise, “not inferable from available authority” is better than guessing.
8. Release marker: resolve the proposed tag and record its actual target. Tag existence is not proof of a release event.
9. Reversal/rollback boundary: state what Git-level reversal covers and what external state remains outside it.
10. Decision: record ACCEPT, MODIFY, REJECT, or BOUNDED_DEFER, plus residual risk and a non-claim.

Why a clean apply can mislead you

cherry-pick applies the change introduced by an existing commit in the current context. If the patch fits the textual context, the operation can finish without a conflict. That success adds no evidence about hidden behavioral dependencies or a compatibility contract.

In the central case, a refactor on main adds a helper. A later bugfix changes only the consumer to use that helper. Everything passes on main. On the older release line, the bugfix itself can apply cleanly while the helper is missing, so a runtime or target test exposes the dependency. The first invalid promotion is: “patch applied cleanly → backport is compatible.”

The same discipline applies to merge and rebase. Git can perform the history operation correctly while release acceptance still requires target-specific evidence. The transfer method is one field in the record, not the verdict.

The instructional flow is: source/target boundary → ancestry/dependency check → candidate method → Git result → target behavior evidence → version/tag boundary → reversal limit → human decision. There is no direct arrow from “operation succeeded” to ACCEPT.

Worked example: a bugfix that depends on a refactor

Suppose main contains a base commit, then a refactor that adds a normalize_code helper, then a bugfix that changes service.py to use it. release/1.4 comes from the older line and does not contain the helper.

Cherry-picking only the bugfix is tempting: the change is small and Git may apply it without a conflict. A defensible record, however, keeps Git operation result separate from target-line behavior result. If the release test fails because the dependency is missing, the clean apply cannot support acceptance.

Several bounded choices can remain: transfer the prerequisite too, reconstruct the fix for the release line, use another integration method, or defer/reject the change. No choice is correct because of its method name. Inspect the target-line scope and compatibility boundary, then choose the option that makes the smallest justified claim with sufficient evidence.

The training fixture intentionally declares no SemVer/public-API policy. Therefore a tag that looks like v1.4.1 does not authorize a PATCH inference. The candidate tag may also point to the pre-fix commit; resolve its actual target instead of trusting the name.

Four shortcuts to stop

“The cherry-pick was clean, so the backport is safe.” Check the dependency boundary and target-specific behavior.

“We reverted it, so the system is rolled back.” Separate Git-tracked state from database, file, message, or service side effects and record external recovery obligations.

“The release tag is named correctly, so that version is deployed.” Resolve the tag target and keep deployment/publication evidence separate.

“It is a bugfix, so SemVer says PATCH.” First establish that the project explicitly adopts SemVer and declares a public API. Without that authority, do not infer the bump.

“AI or a tool says risk is low.” A tool may suggest probes or hypotheses, but acceptance remains a human decision tied to independently inspectable evidence.

For experienced engineers: preserve team policy and the claim boundary

Your team may use release branches, maintenance lines, trunk, merge queues, or backport automation. This lesson does not mandate a workflow. Preserve these invariants:

• exact source and target;
• inspectable ancestry and prerequisite boundary;
• context-specific method rationale;
• target-line verification independent of Git success;
• tag target separate from release/deployment evidence;
• version policy only with explicit authority;
• reversal boundary separate from operational rollback;
• explicit residual risk and human decision.

If internal tooling records the same meaning under different field names, the artifact may mirror it. The semantics must remain recoverable.

Merge, rebase, cherry-pick, and reconstruction without dogma

Merge can fit when joining histories matches project policy and the target objective. A successful merge still does not establish behavioral acceptance.

Rebase reapplies commits on another base and changes ancestry. It can be useful for some local histories and inappropriate for some shared or release histories; there is no universal rule here.

Cherry-pick is useful for transferring selected commit changes, but dependencies outside the patch can remain hidden. A clean apply is one observation.

Reconstruction/minimal backport can sometimes reproduce the fix without bringing a larger refactor. It still needs target-specific tests and rationale; a smaller diff is not safety evidence by itself.

Revert is a history-level reversal tool. If an incident has external side effects, the record needs a separate recovery plan for those states.

Lab and independent practice

Build FND010-LAB1. The local fixture contains main, release/1.4, local tags, deterministic tests, and a synthetic external-state marker. It uses no remote repository, credentials, or production system.

For S2, capture the source commit and target ancestry first. Evaluate a candidate transfer and record the Git result separately from the target test result. If a clean cherry-pick produces a behavioral failure, keep that observation. Choose the correction method yourself; the oracle does not enforce one command sequence, but target behavior, rationale, tag target, version-policy boundary, and reversal limitation must be reviewable.

For S5, the second fixture puts the target line one commit further behind, keeps the fix reconstructable without the refactor, and puts the candidate tag on the wrong ancestor. Rebuild ancestry and evidence instead of copying the first case’s strategy.

Minimum defensible evidence package

Release-Aware Change Control Record v1 includes the source commit, target ref/tip, ancestry evidence, dependency assumption plus a proof or probe, candidate method and rationale, Git operation result, target behavior evidence, version-policy applicability, proposed tag and resolved target, reversal/rollback boundary, external-state observation, residual risk, human decision, non-claim, and support disclosure.

Evidence must be able to falsify the decision. “No conflicts,” “CI was green,” or “the tag exists” is sufficient only for a claim bounded to exactly that observation. A broader claim needs broader evidence.

When evidence is incomplete, BOUNDED_DEFER can be more defensible than false certainty. Record what decision is deferred and what evidence would close it.

Assessment from retrieval to transfer

S1 separates source/target state, transfer method, revert boundary, tag meaning, and version-policy applicability in a compact case.

S2 builds the central Release-Aware Change Control Record v1 from the lab and binds every blocking conclusion to an inspectable locator or observation.

S3 identifies the first unsupported promotion from Git success to compatibility or release acceptance and proposes a discriminating probe.

S4 chooses ACCEPT, MODIFY, REJECT, or BOUNDED_DEFER with rationale, limitation, and a non-claim.

S5 applies the same evidence bar to changed history; copying the previous command sequence is insufficient.

Four dimensions are critical and non-compensatory: state/history correctness, evidence traceability, human judgment/limitation disclosure, and transfer.

Sources and freshness boundary

Technical meanings of cherry-pick, rebase, merge, revert, and tag are bounded to official Git documentation. Version-impact claims are bounded to Semantic Versioning 2.0.0 and apply only where the project explicitly adopts SemVer and declares a public API.

The lesson research map was recorded on 2026-09-02, with command-specific Git sources due for review on 2026-10-17. On 2026-09-07 the same source set was checked again against the official sources; no new claim boundary was introduced. Reverification is required when a source materially changes, review_due expires, or authoring introduces a new current technical claim outside this map.

Release-Aware Change Control Record v1 is a curriculum design rule, not a claim that Git imposes one universal release-management policy.