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

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

[Sean Paul]

Along with a recipe for creating a topic branch and sending a pull
request from it.

Signed-off-by: Sean Paul <seanpaul@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
+-----------------------------
+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.
+
+  $ 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.
+
+  $ 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.
+
+Once you're satisfied that nothing is broken, create the pull request.
+
+  $ dim pull-request topic/*topic-branch* origin/master
+
+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*
+
 CONTRIBUTING
 ============
 
-- 
2.12.2.564.g063fe858b8-goog

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [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@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@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [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@chromium.org>

One more: The maintainer's duties section in drm-misc.rst talks about
topic branches, pls add a link there to this new example here.

Thanks, Daniel

> ---
>  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
> +-----------------------------
> +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.
> +
> +  $ 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.
> +
> +  $ 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.
> +
> +Once you're satisfied that nothing is broken, create the pull request.
> +
> +  $ dim pull-request topic/*topic-branch* origin/master
> +
> +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*
> +
>  CONTRIBUTING
>  ============
>  
> -- 
> 2.12.2.564.g063fe858b8-goog
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [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@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
> +-----------------------------
> +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.
> +
> +  $ 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.
> +
> +  $ 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.
> +
> +Once you're satisfied that nothing is broken, create the pull request.
> +
> +  $ dim pull-request topic/*topic-branch* origin/master
> +
> +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*

s/remote/remove/

-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

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

[Sean Paul]

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(-)

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

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [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@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
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx