This is an old revision of the document!
===== ** WARNING: This process is currently still being refined ** ===== ---- ====== Staging tree ====== {{ :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. 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. ===== Trying out a feature branch ===== 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}} Please be aware that all code within any branch of the staging tree is **completely unsupported**. This means that: * Code found within the staging tree will not necessarily be merged into the main branch. * Code found within the staging tree may be changed in incompatible ways by the time it is merged into the main branch. * You should not rely on code found within the staging tree when building production systems. 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! 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 staging/3c90x 130e421 [3c90x] 3c90x driver rewrite using gPXE API 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 git checkout staging/feature make where ''feature'' is the name of the feature branch that you want to try out. ===== Contributing a new feature ===== {{ :nic.jpeg?237x222|A network card}} 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. 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 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. 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. 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. ===== Management of the staging tree ===== Staging tree maintainers should set up access to the staging tree using git remote add staging git.etherboot.org:/pub/scm/gpxe-staging.git git fetch staging Patches received via the mailing list will be sponsored by one particular staging tree maintainer. In the case where the sponsor is not the patch author, the sponsor should e-mail the contributor and carbon-copy the other staging tree maintainers to indicate the sponsorship. At that point, the sponsor should then add the contributed patch to the staging tree as a new feature branch using git checkout master git pull git checkout -b new_feature-sponsorname git am < new_feature.patch git commit --amend (add a Sponsored-by: tag to the commit message) git push staging new_feature-sponsorname Where "sponsorname" is a short-name for the sponsor. At this point, the sponsor and other maintainers can review the code. Each reviewer (including the sponsor) can check the status of total reviews of the feature branch with git fetch staging git branch -r -v | grep new_feature A reviewer of a branch who is not its sponsor should review the code and indicate the results of the review by renaming their copy of the branch with the following formats: new_feature-reviewer-rej (Reviewer rejection) new_feature-reviewer-fix (Typically will include commits with minor fixes) new_feature-reviewer-ok (To indicate a passing review to the sponsor) Note to reviewers: 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 localname:refs/heads/remotename When the sponsor believes that an appropriate window of opportunity for review has expired, the sponsor can do a final check for reviews, amend their branch head again with applicable "Reviewed-by:", "Modified-by:", and "Rejected-by:" tags in the commit message, and then rename their branch in the staging repository in the following format: new_feature-ready This is an indication to reviewers that the feature has now been handed-off to the lead developer. The lead developer can easily check for branches pending for actual merge review with git branch -a | grep ready Branches named with the -ready suffix cannot be further modified; their ownership will have been effectively transferred to the lead developer. If the feature has been rejected, the sponsor can work with the contributor to see if it can be cleaned up such that it would be suitable. If the sponsor is the contributor, they should wait for at least one other reviewer to indicate a passing review with an -ok branch before naming their submission as a -ready branch for the lead developer's review. 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-sponsorname git checkout -b new_feature-sponsorname git am < new_feature_v2.patch git push staging new_feature-sponsorname --force Be careful when using ''git branch -D'' and ''git push --force'', since it is easy to accidentally delete the wrong branch!
