Staging tree procedures

The staging tree is used to hold branches waiting for potential merging into the main gPXE tree. It provides a central location for collecting patches submitted via the mailing list, IRC, and other methods.

Most branches in the staging tree hold individual features, such as a new driver, and are referred to as “feature branches”.

After a feature branch is merged into the main gPXE tree, it is deleted from the staging tree.

You can build gPXE from any feature branch in the staging tree, if there is a particular new feature that you would like to try out.

By helping to debug a feature branch in the staging tree, you will be helping to accelerate the merging of the feature into the main gPXE tree, and we appreciate your help!

Please be aware that all code within any branch of the staging tree is experimental.

This means that code in the staging tree:

• Will not necessarily be merged into the main branch

• May be changed in incompatible ways by the time it is merged into the main branch

• Should not be relied on in production systems

• May not be actively supported by the sponsor of the branch

To try out a feature branch in the staging tree, you will first need to check out a copy of the gPXE development tree. If you have not already done this, you can do so using

  $ git clone git://git.etherboot.org/scm/gpxe.git

Once you have checked out a copy of the gPXE development tree, you can access the staging tree using

  $ cd gpxe/src
  $ git remote add staging git://git.etherboot.org/scm/gpxe-staging.git
  $ git fetch staging
  $ git branch -r -v

You should see a whole series of staging/feature branches, such as

  staging/mdc-52-subxfix     5c6a1c6 [build] Fix signed/unsigned division in util/zbin.c
  staging/meteger-22-3c90x   130e421 [3c90x] 3c90x driver rewrite using gPXE API

You can check out and build any one of these feature branches using

  $ git checkout staging/feature
  $ make

where feature is the name of the feature branch that you want to try out.

To contribute a new feature, you should create a dedicated feature branch in your local git tree. For example:

  $ git checkout master
  $ git pull
  $ git checkout -b my_feature

You can then make and commit changes to your local git tree; these commits will be placed into the my_feature branch.

Once you are ready to submit your new feature for review, you should send a patch list to the gpxe@etherboot.org mailing list. To send mail to the list you must first join at http://etherboot.org/mailman/listinfo/gpxe.

Please generate your patch list using:

  $ git fetch origin
  $ git rebase origin/master
  $ git format-patch -s --stdout master > my_feature.patch

and send my_feature.patch as an attachment to the mailing list, along with a brief comment describing your patch.

There are some points to bear in mind when submitting code for review:

• Each commit should be reviewable as a standalone unit that makes sense from the point of view of the tree as a whole. For example, a new feature branch that requires some changes to the net device core API should contain at least two commits: one commit to change the net device core API (and to fix up all code affected by this change) and one or more commits to then introduce the new feature.

• There should be no trace of partially-working attempts, abandoned ideas, temporary hacks, and so on. Commands such as:

  $ git rebase --interactive

and

  $ git commit --amend

can be very useful in tidying up a branch so that it is ready to be submitted.

• Each commit must be buildable in its own right. For example, do not introduce a C file in one commit that depends upon a header introduced only in a later commit.

• Each commit should be small enough to be sensibly reviewed in isolation. There are no hard and fast rules, but the easier the commit is to review, the sooner it is likely to be merged into the main gPXE tree.

After a code review, you may need to make changes to your feature branch. You may find it useful to use the command

  $ git rebase --interactive master

in order to edit individual commits within your feature branch. Once you have made any required changes, you can generate a new patch list using

  $ git fetch origin
  $ git rebase origin/master
  $ git format-patch -s --stdout master > my_feature_v2.patch

and send my_feature_v2.patch as an attachment to the mailing list ( gpxe@etherboot.org ).

Staging tree maintainers can set up access to the staging tree using:

  $ git remote add staging git.etherboot.org:/pub/scm/gpxe-staging.git
  $ git fetch staging

All staging tree branches must be sponsored by a staging tree maintainer. In cases where the branch sponsor and code contributor are different people, the sponsor should e-mail the contributor and carbon-copy the other staging tree maintainers ( staging@etherboot.org ) to announce sponsorship of the branch.

Before a branch is added to the staging tree, a task should be created in the http://support.etherboot.org/ site in order to create a task number and to provide a space to record discussion.

The format of staging branch names is:

  sponsor_name-task_number-feature_branch_name

where:

• sponsor_name is the Freenode IRC nickname of the staging maintainer who is sponsoring this branch.
• task_number is the numeric task number assigned by http://support.etherboot.org/ for this task. This field is of variable length depending on the number of digits in the task.
• feature_branch_name is a descriptive name for this branch indicating its purpose.

At this point, the sponsor may add a new feature branch using

  $ git checkout master
  $ git pull
  $ git checkout -b sponsor_name-task_number-feature_branch_name
  $ git am < new_feature.patch
  $ git commit --amend
  (add a Sponsored-by: tag to the commit message)
  $ git push staging sponsor_name-task_number-feature_branch_name

Local copies of the staging repository may be updated with:

  $ git fetch staging

A helpful display of remote branches may be displayed with:

  $ git branch -r -v

A reviewer of a branch who is not its sponsor should review the code and indicate the results of the review by adding comments to the related task on http://support.etherboot.org/ which will notify the task creator and anyone else who is watching the task.

When a sponsor believes that an appropriate window of opportunity for review has expired, they may send a pull request email to staging@etherboot.org. This is an indication to main branch maintainers that the feature is now ready for final merge review.

The email subject should be as follows:

  [PULL REQUEST] sponsor_name-task_number-feature_branch_name

The pull request email message can be generated as follows:

  $ # Currently on the staging branch
  $ git request-pull master git://git.etherboot.org/scm/gpxe-staging.git

Note to staging tree maintainers:

• When pushing a new branch under a different name than it has locally, you cannot abbreviate the remote ref; you need something like

  $ git push staging local_name:refs/heads/remote_name

Main repository maintainers respond to the pull request email by performing final review and merging the branch if it passes review.

Branches named with the -ready suffix should not be further modified; their ownership has been effectively transferred to the main repository maintainers.

If the branch is accepted and applied, the main repository maintainer who merged the branch will delete it from the staging repository.

If the branch is not accepted the main repository maintainer will contact the staging branch sponsor to discuss what changes would be needed for the branch to be accepted.

If changes are needed the staging branch sponsor should create a new branch with an updated version suffix such as v2 should be created, with an appropriate notation (and possibly a gitweb link) in the http://support.etherboot.org/ tracker for this task.

If a feature branch is rejected by a main repository maintainer, the sponsor can work with the contributor to see if the code can be cleaned up such that it is acceptable.

When an updated version of a patch is received, it should completely replace the previous version of the feature branch. This can be done using

  $ git checkout master
  $ git pull
  $ git branch -D new_feature_name
  $ git checkout -b new_feature_name
  $ git am < new_feature_v2.patch
  $ git push staging sponsor_name-task_number-feature_branch_name_v2

  $ git branch -r -v

  $ git log staging/branch_name

  $ git cherry -v HEAD staging/branch_name

Use the commands below if you want to delete remote branches in your local copy of the staging repository that have been deleted in the the upstream staging repository.

  $ git remote prune --dry-run staging

  $ git remote prune staging

Be very careful with this one:

  $ git push staging :remote_branch_name

The “:” character before the remote_branch_name is required for the push to work.