This is an old revision of the document!
====== Staging tree procedures ====== {{ :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". After a feature branch is 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. ==== Staging branch rules ==== === 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: * 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 staging/mdc-52-subxfix 5c6a1c6 [build] Fix signed/unsigned division in util/zbin.c staging/meteger-22-3c90x 130e421 [3c90x] 3c90x driver rewrite using gPXE API 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}} ==== 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 === $ git branch -r -v $ 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.
