✎ staging - Etherboot/gPXE Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Staging tree ======

{{ :bootrom.jpeg?120x96|A boot ROM}}

The [[http://git.etherboot.org/?p=gpxe-staging.git|staging tree]] is used to hold contributed patches for review and merging into the [[http://git.etherboot.org/?p=gpxe.git|main gPXE tree]].  It provides a central location for collecting patches submitted via the mailing list.

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

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

===== Trying out a feature branch =====

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.

{{ :warning.png?50x43|Warning sign}}

Please be aware that all code within any branch of the staging tree is **completely unsupported**.  This means that:

  * Code found within the staging tree will not necessarily be merged into the main branch.

  * Code found within the staging tree may be changed in incompatible ways by the time it is merged into the main branch.

  * You should not rely on code found within the staging tree when building production systems.

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!

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/3c90x       130e421 [3c90x] 3c90x driver rewrite using gPXE API
    staging/eepro100    92f2d8c [eepro100] Bring mdeck's eepro100 driver to staging
    staging/imgauto     1de3f5b [image] Added imgauto command to fetch, load, execute
    staging/sdsk        89f32b0 [build] Add syslinux floppy image type .sdsk
    staging/subxfix     5c6a1c6 [build] Fix signed/unsigned division in util/zbin.c
    staging/undiheader  e7ce627 [romprefix] Make replacement UNDI ROM optional

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.

===== Contributing a new feature =====

{{ :nic.jpeg?237x222|A network card}}

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 can send a patch list to the [[etherboot-developers@lists.sourceforge.net]] mailing list.  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.

===== Management of the staging tree =====

Staging tree maintainers should set up access to the staging tree using

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

Patches received via the mailing list will be sponsored by one particular staging tree maintainer.  In the case where the sponsor is not the patch author, the sponsor should e-mail the contributor and carbon-copy the other staging tree maintainers to indicate the sponsorship.  At that point, the sponsor should then add the contributed patch to the staging tree as a new feature branch using

    git checkout master
    git pull
    git checkout -b new_feature-sponsorname
    git am < new_feature.patch
    git commit --allow-empty
    (add a Sponsored-by: tag to the commit message)
    git push staging new_feature-sponsorname

Where "sponsorname" is a short-name for the sponsor.  At this point, the sponsor and other maintainers can review the code.  Each reviewer (including the sponsor) can check the status of total reviews of the feature branch with

    git branch -a | grep new_feature

A reviewer of a branch who is not its sponsor should review the code and indicate the results of the review by renaming their copy of the branch with the following formats:

    new_feature-reviewer-rej (Reviewer rejection)
    new_feature-reviewer-fix (Typically will include commits with minor fixes)
    new_feature-reviewer-ok  (To indicate a passing review to the sponsor)

When the sponsor believes that an appropriate window of opportunity for review has expired, the sponsor can do a final check for reviews, then another commit with the applicable "Reviewed-by:", "Modified-by:", and "Rejected-by:" tags in the commit message, and then rename their branch in the staging repository in the following format:

    new_feature-reviewer-ready

This is an indication to reviewers that the feature has now been handed-off to the lead developer.  The lead developer can easily check for branches pending for actual merge review with

    git branch -a | grep ready

No one shall modify a branch named with the -ready suffix; its ownership will have been effectively transferred to the lead developer.

If the feature has been rejected, the sponsor can contact the contributor regarding the matter.

If the sponsor is the contributor, they should wait for at least one other reviewer to indicate a passing review with an -ok branch before naming their submission as a -ready branch for the lead developer's review.

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
    git checkout -b new_feature
    git am < new_feature_v2.patch
    git push staging new_feature --force

Be careful when using ''git branch -D'' and ''git push --force'', since it is easy to accidentally delete the wrong branch!
Trace: • under_construction • mknbi • week10 • week9 • staging • sanboot • journal • winpe • httpfsprobs • week2 • dslbko • week10 • ubuntu_iscsi2 • probsbkoromomatic