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
Last revision Both sides next revision
staging [2009/08/09 18:26]
rwcr
staging [2009/11/22 20:25]
mdc
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 --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)     (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)+
  
-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:+    $ git branch --v
  
-    new_feature-ready+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.
  
-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 then rename their branch in the staging repository in the following format:
  
-Branches named with the -ready ​suffix cannot be further modified; their ownership will have been effectively transferred to the lead developer.+    sponsor_name-task_number-feature_branch_name-ready
  
-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.+This is an indication to main branch maintainers that the feature ​is now ready for final merge review.
  
-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.+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 can easily check for branches pending final merge review with 
 + 
 +    $ git branch -r -v | grep ready 
 + 
 +or by using gitweb to view all branches in the staging repository:​ 
 + 
 +    http://​git.etherboot.org/?​p=gpxe-staging.git;​a=heads 
 + 
 +=== 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-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.

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)