| Message ID | 20170405200004.1921-1-seanpaul@chromium.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Wed, Apr 05, 2017 at 03:59:52PM -0400, Sean Paul wrote: > Along with a recipe for creating a topic branch and sending a pull > request from it. > > Signed-off-by: Sean Paul <seanpaul@chromium.org> Applied, thanks. -Daniel > --- > > Changes in v2: > - Address danvet's comments > - added paragraph about selecting a baseline > - s_origin/master_*baseline*_ > - s/build test/test/ > - add breadcrumb in drm-misc docs > > > dim.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > drm-misc.rst | 3 ++- > 2 files changed, 59 insertions(+), 1 deletion(-) > > diff --git a/dim.rst b/dim.rst > index b99248e..3dd19f9 100644 > --- a/dim.rst > +++ b/dim.rst > @@ -472,6 +472,63 @@ listed using the **list-aliases** subcommand. > > The alias functionality requires **bash(1)** version 4.3 or later to work. > > +EXAMPLES > +======== > + > +Cross-subsystem topic branches > +------------------------------ > +So you want to send a pull request to another subsystem? Maintainers will likely > +get cranky if you ask them to pull a swath of unrelated drm patches, so we'll > +use a topic branch based upon Linus' tree with only the relevant patches. > + > +First select a suitable *baseline* for your topic branch. For topic > +branches shared within the gpu/drm subsystem, base it on the latest > +drm-next branch. For anything else, base it on the latest -rc tag from > +Upstream (not just any random position). In very rare cases you might need > +to apply topic branch pull requests from other maintainers before you can > +apply patches to construct a suitable baseline first. > + > +Next, create the topic branch using dim. Use whichever dim remote is most > +applicable, and name the branch in a manner that describes the set of patches > +you want pulled. The upstream will be Linus' tree. > + > + $ dim create-branch *dim-remote*/topic/*topic-branch* *baseline* > + > +Once the branch is created, you can apply the patches to be pulled. > + > + $ dim apply-branch topic/*topic-branch* > + > +Test your new topic branch and push it. > + > + $ dim push-branch topic/*topic-branch* > + > +Ensure that your topic branch was merged into drm-tip. The drm-tip tree is > +located in $DIM_PREFIX/drm-tip, test it to ensure the new topic branch > +didn't break anything. > + > +Once you're satisfied that nothing is broken, create the pull request. > + > + $ dim pull-request topic/*topic-branch* *baseline* > + > +You'll be prompted to enter a tag description and your mail user agent will open > +with the pull request email. Change names and emails as appropriate to reflect > +who the sender and recipient of the pull is, and send it. > + > +Once the pull has been acked by your maintainer counterpart, you can pull it > +into the appropriate local dim branch. > + > + $ dim apply-pull *dim-branch* > + > +Perform a final test, and push *dim-branch* to *dim-remote*. > + > + $ dim push-branch *dim-branch* > + > +You can now remove the topic branch, as it is no longer useful (you could remove > +it any time after the pull request, since it creates a tag, but this is as good > +a place as any). > + > + $ dim remove-branch topic/*topic-branch* > + > CONTRIBUTING > ============ > > diff --git a/drm-misc.rst b/drm-misc.rst > index 8c6e4bf..45ea795 100644 > --- a/drm-misc.rst > +++ b/drm-misc.rst > @@ -86,7 +86,8 @@ Right now the only hard merge criteria are: > > * Any non-linear actions (backmerges, merging topic branches and sending out > pull requests) are only done by the official drm-misc maintainers (currently > - Daniel, Jani and Sean, see MAINTAINERS), and not by committers. > + Daniel, Jani and Sean, see MAINTAINERS), and not by committers. See the > + `examples section in dim <dim.html#examples>`_ for more info > > * All the x86, arm and arm64 DRM drivers need to still compile. To simplify this > we track defconfigs for all three platforms in the `drm-intel-rerere` branch. > -- > 2.12.2.715.g7642488e1d-goog >
diff --git a/dim.rst b/dim.rst index b99248e..3dd19f9 100644 --- a/dim.rst +++ b/dim.rst @@ -472,6 +472,63 @@ listed using the **list-aliases** subcommand. The alias functionality requires **bash(1)** version 4.3 or later to work. +EXAMPLES +======== + +Cross-subsystem topic branches +------------------------------ +So you want to send a pull request to another subsystem? Maintainers will likely +get cranky if you ask them to pull a swath of unrelated drm patches, so we'll +use a topic branch based upon Linus' tree with only the relevant patches. + +First select a suitable *baseline* for your topic branch. For topic +branches shared within the gpu/drm subsystem, base it on the latest +drm-next branch. For anything else, base it on the latest -rc tag from +Upstream (not just any random position). In very rare cases you might need +to apply topic branch pull requests from other maintainers before you can +apply patches to construct a suitable baseline first. + +Next, create the topic branch using dim. Use whichever dim remote is most +applicable, and name the branch in a manner that describes the set of patches +you want pulled. The upstream will be Linus' tree. + + $ dim create-branch *dim-remote*/topic/*topic-branch* *baseline* + +Once the branch is created, you can apply the patches to be pulled. + + $ dim apply-branch topic/*topic-branch* + +Test your new topic branch and push it. + + $ dim push-branch topic/*topic-branch* + +Ensure that your topic branch was merged into drm-tip. The drm-tip tree is +located in $DIM_PREFIX/drm-tip, test it to ensure the new topic branch +didn't break anything. + +Once you're satisfied that nothing is broken, create the pull request. + + $ dim pull-request topic/*topic-branch* *baseline* + +You'll be prompted to enter a tag description and your mail user agent will open +with the pull request email. Change names and emails as appropriate to reflect +who the sender and recipient of the pull is, and send it. + +Once the pull has been acked by your maintainer counterpart, you can pull it +into the appropriate local dim branch. + + $ dim apply-pull *dim-branch* + +Perform a final test, and push *dim-branch* to *dim-remote*. + + $ dim push-branch *dim-branch* + +You can now remove the topic branch, as it is no longer useful (you could remove +it any time after the pull request, since it creates a tag, but this is as good +a place as any). + + $ dim remove-branch topic/*topic-branch* + CONTRIBUTING ============ diff --git a/drm-misc.rst b/drm-misc.rst index 8c6e4bf..45ea795 100644 --- a/drm-misc.rst +++ b/drm-misc.rst @@ -86,7 +86,8 @@ Right now the only hard merge criteria are: * Any non-linear actions (backmerges, merging topic branches and sending out pull requests) are only done by the official drm-misc maintainers (currently - Daniel, Jani and Sean, see MAINTAINERS), and not by committers. + Daniel, Jani and Sean, see MAINTAINERS), and not by committers. See the + `examples section in dim <dim.html#examples>`_ for more info * All the x86, arm and arm64 DRM drivers need to still compile. To simplify this we track defconfigs for all three platforms in the `drm-intel-rerere` branch.
Along with a recipe for creating a topic branch and sending a pull request from it. Signed-off-by: Sean Paul <seanpaul@chromium.org> --- Changes in v2: - Address danvet's comments - added paragraph about selecting a baseline - s_origin/master_*baseline*_ - s/build test/test/ - add breadcrumb in drm-misc docs dim.rst | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ drm-misc.rst | 3 ++- 2 files changed, 59 insertions(+), 1 deletion(-)