Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
staging [2009/08/09 17:25]
andytim Staging tree maintainer reviewflow
staging [2010/01/15 13:00] (current)
stefanha
Line 1: Line 1:
-====== Staging tree ======+====== Staging tree procedures ​======
  
 {{ :​bootrom.jpeg?​120x96|A boot ROM}} {{ :​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"​. 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 ===== ===== 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. 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 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 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 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 ​[3c90x3c90x 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 ​[romprefixMake replacement UNDI ROM optional+
  
 You can check out and build any one of these feature branches using 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. 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}} {{ :​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: 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. 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. 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: 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.   * 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 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.   * 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 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 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 ===== ===== 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 --allow-empty+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)     (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 branch -a | grep new_feature+Local copies of the staging repository may be updated with:
  
-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)+
  
-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:+    $ git branch ​--v
  
-    new_feature-reviewer-ready+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.
  
-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+=== Indicating readiness ​for final merge review ​===
  
-    git branch -| grep ready+When 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.
  
-No one shall modify a branch named with the -ready suffix; its ownership will have been effectively transferred to the lead developer.+The email subject should be as follows:
  
-If the feature has been rejected, the sponsor can contact the contributor regarding the matter.+    [PULL REQUEST] sponsor_name-task_number-feature_branch_name
  
-If the sponsor ​is the contributorthey should wait for at least one other reviewer ​to indicate ​passing review ​with an -ok branch before naming their submission ​as a -ready branch ​for the lead developer'​s review.+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 appliedthe 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 ​new branch ​with an updated version suffix such as ''​v2''​ should be created, with an appropriate notation (and possibly ​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 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 +    ​git branch -D new_feature_name 
-    git checkout -b new_feature +    ​git checkout -b new_feature_name 
-    git am < new_feature_v2.patch +    ​git am < new_feature_v2.patch 
-    git push staging ​new_feature ​--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.

Navigation

* [[:start|Home]] * [[:about|About our Project]] * [[:download|Download]] * [[:screenshots|Screenshots]] * Documentation * [[:howtos|HowTo Guides]] * [[:appnotes|Application Notes]] * [[:faq:|FAQs]] * [[:doc|General Doc]] * [[:talks|Videos, Talks, and Papers]] * [[:hardwareissues|Hardware Issues]] * [[:mailinglists|Mailing lists]] * [[http://support.etherboot.org/|Bugtracker]] * [[:contributing|Contributing]] * [[:editing_permission|Wiki Edit Permission]] * [[:wiki:syntax|Wiki Syntax]] * [[:contact|Contact]] * [[:relatedlinks|Related Links]] * [[:commerciallinks|Commercial Links]] * [[:acknowledgements|Acknowledgements]] * [[:logos|Logo Art]]

QR Code
QR Code staging (generated for current page)