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 17:50] mdc |
staging [2010/01/15 13:00] (current) stefanha |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| {{ :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 branches with 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 61: | 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 69: | 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 79: | 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 84: | 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 <code>git rebase --interactive</code> and <code>git commit --amend</code> 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 111: | 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 157: | 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 169: | 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 199: | 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 ==== | ==== Some useful git commands for staging maintainers ==== | ||
| === Ways to view the staging repository === | === Ways to view the staging repository === | ||
| + | |||
| + | == View compact listing of remote branches == | ||
| $ git branch -r -v | $ git branch -r -v | ||
| + | |||
| + | == Look at staging branch commits == | ||
| + | |||
| $ git log staging/branch_name | $ 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 === | === Prune remote branches from local repository === | ||
| Line 226: | Line 249: | ||
| The ":" character before the remote_branch_name is required for the push to work. | The ":" character before the remote_branch_name is required for the push to work. | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
