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

[Daniel Vetter]

On Mon, Apr 03, 2017 at 01:42:18PM -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>
> ---
>  dim.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)
> 
> diff --git a/dim.rst b/dim.rst
> index bc4d9a0..4b905ad 100644
> --- a/dim.rst
> +++ b/dim.rst
> @@ -465,6 +465,56 @@ listed using the **list-aliases** subcommand.
>  
>  The alias functionality requires **bash(1)** version 4.3 or later to work.
>  
> +EXAMPLES
> +========
> +
> +Cross-subsystem pull requests

s/pull requests/topic branches/ maybe?

> +-----------------------------
> +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, 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.

Even before that we need a few more words about the baseline.

"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 befor you can
apply patches to construct a suitable baseline first.

"Then create the topic ..."

> +
> +  $ dim create-branch *dim-remote*/topic/*topic-branch* origin/master
> +
> +Once the branch is created, you can apply the patches to be pulled.
> +
> +  $ dim apply-branch topic/*topic-branch*
> +
> +Build test your new topic branch and push it.

s/Build test/Test/ ... we might want to have CI and cool stuff eventually.

> +
> +  $ 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, build test it to ensure the new topic branch
> +didn't break anything.

Same.

> +
> +Once you're satisfied that nothing is broken, create the pull request.
> +
> +  $ dim pull-request topic/*topic-branch* origin/master

s/origin\/magster/*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 build 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 remote-branch topic/*topic-branch*

Besides the nits lgtm.
-Daniel

> +
>  CONTRIBUTING
>  ============
>  
> -- 
> 2.12.2.564.g063fe858b8-goog
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx

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