Patch Tracking

draft

The toolchain group works mainly upstream and will, over time, endeavor to minimise the differences with upstream. This page describes the different classes of change and how the patches will be tracked.

Classes

Changes are handled differently depending on where they are developed.

Upstream changes:

  • are developed upstream in the upstream VCS
  • are backported to the Linaro branch
  • are picked up when Linaro rebases to the appropriate upstream version

The patch is tracked until the rebase.

These changes include:

  • new features
  • fixes

Local changes:

  • are developed on the Linaro branch
  • are sent upstream where they may be:
    • accepted as-is
    • modified
    • rejected

Accepted fixes are tracked until the rebase. Modified fixes are modified on the Linaro branch and tracked until the rebase. Rejected patches are tracked forever.

These changes include:

  • fast fixes, where something needs to be done for a release

A local change may later be refined or superceeded upstream. Tracking this is outside the scope of the patch tracker and should lead to new work items.

Local only changes:

  • are developed on the Linaro branch
  • are never sent upstream

These patches are tracked forever.

These changes include:

  • ARM changes which are not generally applicable and cannot be made so
  • changes with copyright issues. Generally these should be
    • refactored or rewritten instead
  • build specific changes, such as a Linaro version number or build
    • scripts
  • changes that are relevant to a version, but have been superseded upstream

Rebasing

Rebasing occurs when the Linaro toolchain re-synchronises with an upstream release. As most changes are already upstream, only a small set of changes should end up being carried forward.

For example:

  • Linaro is working on a 4.5 based release
  • FSF 4.6 is in stage 3 and not accepting new features
  • Changes are done upstream in what will become 4.7
  • Changes are backported to Linaro 4.5
  • Later when Linaro re-bases on 4.6, this change is manually carried forward from Linaro 4.5 to Linaro 4.6
  • Later when Linaro re-bases on 4.7, the change is pulled in from upstream. The local change is discarded


Method 1

The status of a change is tracked through a Launchpad ticket. The 'Affects' feature is used to track the local versus upstream status.

Upstream changes:

  • Manually create a new ticket when the upstream work starts
  • Record any interesting information in the ticket history

Once accepted upstream:

  • Mark the ticket with the FSF VCS revision the feature appeared in
  • Mark the ticket as affecting the Linaro GCC Tracking (gcc-linaro-tracking) project and target the milestone to the FSF GCC version the change will appear in
  • Marking the tracking bug as 'Fix Committed'
  • Backport the changes into a topic branch
  • Merge the topic branch

Local changes:

These will often be due to a bug. Use the existing ticket instead of making a new one.

  • Develop the fix on a topic branch
  • Submit the change upstream
  • Mark the tracking bug as 'In Progress'
  • Record a link to the email in the ticket
  • Record links to any interesting emails in the ticket

If the change is rejected:

  • Record a link to the reason
  • Mark the tracking bug as 'Won't Fix'
  • Target the tracking bug to the 'never: rejected' milestone

Otherwise:

  • Record a link to the final acceptance
  • Mark the tracking bug as 'Fix Committed'
  • Backport any modifications into the topic branch
  • Mark the ticket with the FSF VCS revision the feature appeared in
  • Mark the ticket as affecting the Linaro GCC Tracking (gcc-linaro-tracking) project and target the milestone to the FSF GCC version the change will appear in

No matter what:

  • Merge the topic branch

Local only changes:

  • Develop the fix on a topic branch
  • Mark the ticket as affecting the Linaro GCC Tracking (gcc-linaro-tracking) project and assign it against the appropriate 'never' milestone
  • Merge the topic branch

Connecting revisions and tickets

The prefered way is to use the bzr --fixes lp:1234 feature when committing a merge or revision. Alternatively, add a message to the ticket with the text related: fully-qualified-revision-name such as related: lp:gcc-linaro/4.4,revno=1234 after the commit. Note that a ticket can be related to multiple revisions on multiple branches.

See https://bugs.launchpad.net/gcc-linaro/+bug/618467 for an example. Note it uses the older fixed-in style.

Marking local changes

The never series is divided up into different milestones to represent the reason a change won't go upstream. These milestones are:

  • rejected - upstream rejected the patch
  • target-specific - a specific version of rejected where the patch has value for ARM but isn't acceptable upstream
  • rebase - the revsion was due to rebasing against upstream, such as pulling in 4.5.1
  • release-related - the revision was due to the release process, such as being a note in the ChangeLog or a bumping of a version number

  • side-effect - the revision is a side-effect of another change, such as updates to .class files due to a .java update.

PENDING: side-effect could link to the actual ticket.

Implementation 1

All revisions on mainline will have a corresponding ticket.

A tool will be written that:

  • Checks for missed items by
    • Showing all revisions that have no ticket
    • Showing all revisions that have a ticket but aren't marked as affecting gcc-linaro-tracking
  • Reports on the patch status by
    • Showing all tickets against mainline
    • Highlighting tickets by state (to upstream, in progress, accepted, rejected)
    • Highlights changes by class (upstream, local, local only)
    • Shows the upstream revision a change appears in


Method 2

This method does not require any manual steps for tracking new revisions. It only requires user input when a patch status changes, or if it is known that no upstream submission is required.

The examples below assume that the current local milestone is 4.5, and the current upstream milestone is 4.6.

Local-first changes

  1. The developer commits a change to bzr/git/whatever.
  2. An automated "trackerbot" sees the new revision and creates a new ticket in the gcc-linaro-tracking project:

    • Summary:
      • [4.5/r99999] First line of commit message
      Assigned To:
      • <The developer who committed the revision>
      Milestone:
      • GCC 4.6
      Description:
      • Revision: [link to revision page]
        Bug: [link to original bug fix]
        Bug: [link to another fixed bug]
        
        Entire commit message
        .....
  3. The developer adds textual info to the bug, reassigns it to proper person, and whatever else they need.
  4. The assignee starts the upstream submission process, adds links to upstream discussion, and anything else of interest, and sets the tracker state to "in-progress".
    1. The patch is accepted upstream, so the assignee sets the state to "Committed".
    2. The patch is rejected upstream, so the assignee sets the state to "wont fix", and changes the series->milestone to "never->4.5".

Backports from upstream

  1. As above
  2. As above
  3. The committer selects the upstream milestone corresponding to the source of the patch, and sets the state to "committed".

Local-only changes

  1. As above
  2. As above
  3. The committer sets the series->milestone to "never->4.5" and sets the state to either "won't fix", for patches we expect to carry, or "invalid", for one-time changes (such as version bumps).

Upstream-first changes

The developer may choose to do these however they wish, however as in method 1, it may be good policy to maintain a launchpad ticket to track development. Unlike method 1, I do not suggest every changing this bug to "affect" gnu-linaro-tracking. Only the automatically created tickets should affect that project.

Once the patch is complete, it may well be backported and the procedure above followed.

Notes

We did originally discuss reusing bug tickets for tracking the upstream submission state. However I now believe this is a bad plan:

  • The patch tracking comments might get lost among the other comments.
  • Bugs that produce multiple commits will have to be tracked multiple times, which is just confusing.
  • Commits that fix multiple bugs are not straight-forward.

However, I do this it would be good policy to include references to the original bug in the tracker ticket, and insert a comment in the original ticket that references back to the tracker ticket.

We need the "never" series to have milestones for each local branch when we rebase. For example, when creating a new gcc 4.6 branch, we probably only want to forward the patches from gcc 4.5. Having only one "never" milestone will mean that we would also have to consider all the patches in 4.4. That's probably not to many, but imagine when we want to rebase to 4.9!

Implementation 2

All revisions on all local branches will have a tracking ticket.

A tool will be created that:

  • scans the bzr revisions, and creates a launchpad ticket for each.
  • inserts links to the new ticket into bugs referenced by --fixes on commit.

Reports will be obtained from the standard Launchpad web interface:

  • Patches to upstream
    • Open tickets against the current upstream milestone.
  • Patches required on rebase
    • All tickets (closed and open) against all upstream milestones newer than the new baseline.

    • Open tickets against milestone "never->x.x" where x.x is the version of the outgoing toolchain version.

WorkingGroups/ToolChain/PatchTracking (last modified 2010-08-17 10:26:48)