Differences

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

Link to this comparison view

Next revision
Previous revision
Last revision Both sides next revision
staging [2009/08/01 14:21]
mcb30 created
staging [2009/11/22 20:25]
mdc
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"​. 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 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 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.
  
-==== 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 then rename their branch in the staging repository in the following format: 
 + 
 +    sponsor_name-task_number-feature_branch_name-ready 
 + 
 +This is an indication to main branch maintainers that the feature is now ready for final merge 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 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.

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)