Differences
This shows you the differences between two versions of the page.
| 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 a 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. | ||
