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/11/21 16:42]
mdc Change process to use http://support.etherboot.org/
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 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, IRC, and other methods.+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 is merged into the main gPXE tree, it will be 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 **experimental**.+=== How and why you can help === 
 + 
 +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! 
 + 
 +=== 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: This means that code in the staging tree:
Line 27: Line 33:
   * May not be actively supported by the sponsor of the branch   * May not be actively supported by the sponsor of the branch
  
-That being said, 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 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
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:
Line 63: Line 71:
  
 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.
 +
 +==== 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]]. 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]].
Line 73: Line 83:
  
 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 78: 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
Line 94: Line 116:
     $ 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 ( [[gpxe@etherboot.org]] )+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 =====
Line 105: Line 127:
     $ git fetch staging     $ git fetch staging
  
-All staging tree branches must be sponsored by a staging tree maintainer. ​ In cases where 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 ​the sponsorship of the branch.  ​+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 ==== ==== Creating a support tracker task ====
Line 151: Line 173:
 === Indicating readiness for final merge review === === 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:+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.
  
-   ​sponsor_name-task_number-feature_branch_name-ready+The email subject should be as follows:
  
-This is an indication to reviewers that the feature has now been handed off for final merge review to a main repository maintainer.+    [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: ​ Note to staging tree maintainers: ​
Line 163: Line 190:
     $ git push staging local_name:​refs/​heads/​remote_name     $ git push staging local_name:​refs/​heads/​remote_name
  
-Main repository maintainers ​can easily check for branches pending ​final merge review ​with +Main repository maintainers ​respond to the pull request email by performing ​final review ​and merging ​the branch if it passes review.
- +
-    $ 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 === === Final merge review procedure ===
Line 193: Line 214:
     $ git am < new_feature_v2.patch     $ git am < new_feature_v2.patch
     $ git push staging sponsor_name-task_number-feature_branch_name_v2     $ 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:
 +
 +    $ git push staging :​remote_branch_name
  
 +The ":"​ character before the remote_branch_name is required for the push to work.

QR Code
QR Code staging (generated for current page)