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/02 04:47]
mcb30
staging [2010/01/15 13:00]
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 treeand 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:
  
-==== Building from the staging tree using git ====+  * Will not necessarily be merged into the main branch
  
-If you already have a clone of the main gPXE tree, you can access ​the staging tree by doing+  * May be changed in incompatible ways by the time it is merged into the main branch
  
-    cd gpxe/src +  * Should not be relied on in production systems
-    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+  * May not be actively supported by the sponsor ​of the branch
  
-    staging/​3c90x ​      ​130e421 [3c90x] 3c90x driver rewrite using gPXE API +=== Git instructions for trying a feature branch ===
-    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+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 checkout staging/feature +    ​git clone git://​git.etherboot.org/​scm/​gpxe.git
-    make+
  
-where ''​feature''​ is the name of the feature branch that you want to try out.+Once you have checked out a copy of the gPXE development tree, you can access the staging tree using
  
-==== Building from the staging ​tree using rom-o-matic ====+    $ cd gpxe/src 
 +    $ git remote add staging ​git://​git.etherboot.org/​scm/​gpxe-staging.git 
 +    $ git fetch staging 
 +    $ git branch -r -v
  
-If you are not building gPXE from source, you can obtain ​pre-built binary ​of gPXE for any of the current ​feature branches ​from [[http://​rom-o-matic.net/​|rom-o-matic]]. ​ Please note that this is provided only for convenience; ​as with all code from the staging tree, these binaries are **completely unsupported** and you should use the code only if you are prepared to help debug it.+You should see whole series ​of ''​staging/​feature'' ​branches, such as
  
-###### ​mdc - please fill in the correct URL for rom-o-matic'​s ​staging ​tree builds #####+    staging/mdc-52-subxfix ​    ​5c6a1c6 [build] Fix signed/​unsigned division ​in util/​zbin.c 
 +    staging/​meteger-22-3c90x   ​130e421 [3c90x] 3c90x driver rewrite using gPXE API 
 + 
 +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 ===== ===== Contributing a new feature =====
  
 {{ :​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 80: 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 should be added to the staging ​tree as a new feature branch using 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 +==== Creating a support tracker task ==== 
-    git am < new_feature.patch + 
-    git push staging ​new_feature+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 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)