[Intel-gfx] [maintainer-tools PATCH v2] dim: Add examples section to dim.rst

[Daniel Vetter]

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 at 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
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch