Differences

This shows you the differences between two versions of the page.

--- staging [2009/08/01 14:21]
mcb30 created
+++ staging [2010/01/15 13:00] (current)
stefanha
@@ Line 1: / Line 1: @@
-====== Staging tree ======
+====== Staging tree procedures ======
-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.
+{{ :bootrom.jpeg?120x96|A boot ROM}}
+The [[http://git.etherboot.org/?p=gpxe-staging.git|staging tree]] is used to hold branches waiting for potential 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, 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".
-===== Building from the staging tree =====
+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.  Please be aware that all code within any branch of the staging tree is **completely unsupported**, and you should use the code only if you are prepared to help debug it.
+===== Trying out a feature branch =====
-==== Building from the staging tree using git ====
+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.
-If you already have a clone of the [[http://git.etherboot.org/?p=gpxe.git|main gPXE tree]], you can access the [[http://git.etherboot.org/?p=gpxe-staging.git|staging tree]] by doing
+==== Staging branch rules ====
-    cd gpxe/src
+=== How and why you can help ===
-    git remote add staging git://git.etherboot.org/scm/gpxe-staging.git
-    git fetch staging
+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!
-    git branch -r -v
+=== What you should know ===
+{{ :warning.png?50x43|Warning sign}} 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
+=== Git instructions for trying a feature 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/3c90x       130e421 [3c90x] 3c90x driver rewrite using gPXE API
+    staging/mdc-52-subxfix     5c6a1c6 [build] Fix signed/unsigned division in util/zbin.c
-    staging/eepro100    92f2d8c [eepro100] Bring mdeck's eepro100 driver to staging
+    staging/meteger-22-3c90x   130e421 [3c90x] 3c90x driver rewrite using gPXE API
-    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
+    $ git checkout staging/feature
-    make
+    $ make
 where ''feature'' is the name of the feature branch that you want to try out.
-==== Building from the staging tree using [[http://rom-o-matic.net/|rom-o-matic]] ====
+===== Contributing a new feature =====
+{{ :nic.jpeg?237x222|A network card}}
+==== Creating a new feature branch ====
+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.
+==== Formatting and submitting a patch for review ====
+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.
+=== Patch structure guidelines ===
+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.
+==== Modifying a patch for resubmission ====
+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]] ).
+===== Management of the staging tree =====
+==== Setting up access ====
+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.
+==== Creating a support tracker task ====
+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.
+==== Creating and naming a staging branch ====
+=== Naming a staging brach ===
+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.
+=== Creating a feature branch ===
+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
+=== Updating local copies of the staging repository ===
+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.
+=== Indicating readiness for final merge review ===
+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.
+=== Final merge review procedure ===
+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.
+=== Updating feature branches ===
+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
+==== Some useful git commands for staging maintainers ====
+=== Ways to view the staging repository ===
+== View compact listing of remote branches ==
+    $ git branch -r -v
+== Look at staging branch commits ==
+    $ git log staging/branch_name
+== Show commits in staging branch not in main branch ==
+    $ git cherry -v HEAD staging/branch_name
+=== Prune remote branches from local repository ===
+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.
+== Do dry run ==
+    $ git remote prune --dry-run staging
+== Really do it ==
+    $ git remote prune staging
+=== Delete remote branch ===
-###### mdc - please fill in here - is it possible to build arbitrary branches via rom-o-matic? #####
+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.

Trace:

Differences

Navigation

Search

Toolbox

QR Code