Differences

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

--- staging [2009/08/09 23:23]
rwcr
+++ staging [2010/01/15 13:00] (current)
stefanha
@@ Line 1: / Line 1: @@
-====== Staging tree ======
+====== Staging tree procedures ======
 {{ :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.
+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".
-Once a feature branch has been merged into the main gPXE tree, it is deleted from the staging tree.
+After a feature branch is merged into the main gPXE tree, it is deleted from the staging tree.
 ===== Trying out a feature branch =====
@@ Line 13: / Line 13: @@
 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}}
+==== Staging branch rules ====
-Please be aware that all code within any branch of the staging tree is **completely unsupported**.  This means that:
+=== How and why you can help ===
-  * Code found within the staging tree will not necessarily be merged into the main branch.
+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!
-  * Code found within the staging tree may be changed in incompatible ways by the time it is merged into the main branch.
+=== What you should know ===
-  * You should not rely on code found within the staging tree when building production systems.
+{{ :warning.png?50x43|Warning sign}} Please be aware that all code within any branch of the staging tree is **experimental**.
-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!
+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
+    $ 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
+    $ cd gpxe/src
-    git remote add staging git://git.etherboot.org/scm/gpxe-staging.git
+    $ git remote add staging git://git.etherboot.org/scm/gpxe-staging.git
-    git fetch staging
+    $ git fetch staging
-    git branch -r -v
+    $ 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.
@@ Line 55: / Line 61: @@
 {{ :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 checkout master
-    git pull
+    $ git pull
-    git checkout -b my_feature
+    $ 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
+==== Formatting and submitting a patch for review ====
-    git fetch origin
+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]].
-    git rebase origin/master
-    git format-patch -s --stdout master > my_feature.patch
+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:
@@ Line 76: / Line 90: @@
   * 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.
+  * 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
+    $ 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 fetch origin
-    git rebase origin/master
+    $ git rebase origin/master
-    git format-patch -s --stdout master > my_feature_v2.patch
+    $ git format-patch -s --stdout master > my_feature_v2.patch
-and send ''my_feature_v2.patch'' as an attachment to the mailing list.
+and send ''my_feature_v2.patch'' as an attachment to the mailing list ( [[gpxe@etherboot.org]] ).
 ===== Management of the staging tree =====
-Staging tree maintainers should set up access to the staging tree using
+==== Setting up access ====
-    git remote add staging git.etherboot.org:/pub/scm/gpxe-staging.git
+Staging tree maintainers can set up access to the staging tree using:
-    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 remote add staging git.etherboot.org:/pub/scm/gpxe-staging.git
+    $ git fetch staging
-    git checkout master
+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.
-    git pull
-    git checkout -b new_feature-sponsorname
+==== Creating a support tracker task ====
-    git am < new_feature.patch
-    git commit --amend
+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 new_feature-sponsorname
+    $ git push staging sponsor_name-task_number-feature_branch_name
-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
+=== Updating local copies of the staging repository ===
-    git fetch staging
+Local copies of the staging repository may be updated with:
-    git branch -r -v | 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:
+    $ git fetch staging
-    new_feature-reviewer-rej (Reviewer rejection)
+A helpful display of remote branches may be displayed with:
-    new_feature-reviewer-fix (Typically will include commits with minor fixes)
-    new_feature-reviewer-ok  (To indicate a passing review to the sponsor)
-Note to reviewers: when pushing a new branch under a different name than it has locally, you cannot abbreviate the remote ref; you need something like
+    $ git branch -r -v
-    git push staging localname:refs/heads/remotename
-When the sponsor believes that an appropriate window of opportunity for review has expired, the sponsor can do a final check for reviews, amend their branch head again with 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:
+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.
-    new_feature-ready
+=== Indicating readiness for final merge review ===
-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
+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.
-    git branch -a | grep ready
+The email subject should be as follows:
-Branches named with the -ready suffix cannot be further modified; their ownership will have been effectively transferred to the lead developer.
+    [PULL REQUEST] sponsor_name-task_number-feature_branch_name
-If the feature has been rejected, the sponsor can work with the contributor to see if it can be cleaned up such that it would be suitable.
+The pull request email message can be generated as follows:
-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.
+    $ # 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 checkout master
-    git pull
+    $ git pull
-    git branch -D new_feature-sponsorname
+    $ git branch -D new_feature_name
-    git checkout -b new_feature-sponsorname
+    $ git checkout -b new_feature_name
-    git am < new_feature_v2.patch
+    $ git am < new_feature_v2.patch
-    git push staging new_feature-sponsorname --force
+    $ 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 ===
+Be very careful with this one:
-Be careful when using ''git branch -D'' and ''git push --force'', since it is easy to accidentally delete the wrong branch!
+    $ 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