[Intel-gfx] [maintainer-tools PATCH 2/2] dim: add a QUICKSTART section to dim.rst

[Jani Nikula]

On Thu, 03 Dec 2015, Paulo Zanoni <paulo.r.zanoni at intel.com> wrote:
> Because just running dim help doesn't give you the greater picture of
> the workflow. All the text here is based on an email written by Daniel
> Vetter, so the credits go to him. Any mistakes were introduced by me.

We could bikeshed the text ad infinitum, but this is better than
nothing, and can be improved upon. LGTM.

BR,
Jani.

PS. I did reply with "reviewed-by" on the previous patch, but we haven't
really tracked those for maintainer tools. Just getting an ack/lgtm is
enough.


>
> Credits-to: Daniel Vetter <daniel.vetter at ffwll.ch>
> Signed-off-by: Paulo Zanoni <paulo.r.zanoni at intel.com>
> ---
>  dim.rst | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 58 insertions(+)
>
> diff --git a/dim.rst b/dim.rst
> index d5ec5c8..567bcb8 100644
> --- a/dim.rst
> +++ b/dim.rst
> @@ -309,6 +309,64 @@ DIM_TEMPLATE_SIGNATURE
>  ----------------------
>  Path to a file containing a signature template for pull request mails.
>  
> +QUICKSTART
> +==========
> +
> +For getting started grab the latest drm (drm-intel-maintainer) script from::
> +
> +    http://cgit.freedesktop.org/drm-intel/tree/dim?h=maintainer-tools
> +
> +There's also a sample config file for ~/.dimrc::
> +
> +    http://cgit.freedesktop.org/drm-intel/tree/dimrc.sample?h=maintainer-tools
> +
> +Plus, there's bash completion in the same directory if you feel like using that.
> +Run::
> +
> +    $ dim help
> +
> +for tons of details about this thing works. Adjust your .dimrc to match your
> +setup and then run::
> +
> +    $ dim setup
> +
> +This will also check out the latest maintainer-tools branches, so please replace
> +the dim you just downloaded with a symlink after this step. And by the way, if
> +you have improvements for dim, please submit them to intel-gfx.
> +
> +You should now have a main repository for patch application. The directory
> +corresponding to this repository is defined by DIM_DRM_INTEL in your .dimrc.
> +You should also have directories called maintainer-tools, drm-intel-nightly (for
> +rebuilding the tree), and drm-intel-rerere for some dim-internal book-keeping.
> +
> +Applying patches to dinq is done in the main repository with::
> +
> +    $ cat patch.mbox | dim apply-queued
> +
> +This works like a glorified version of git apply-mbox and does basic patch
> +checking and adds stuff like patchwork links of the merged patch. It is
> +preferred to use the patch email file instead of the original patch file since
> +it contains some interesting headers like the message ID. When you're happy
> +(remember that with a shared tree any mistake is permanent and there's no
> +rebasing) push out the new tree with::
> +
> +    $ dim push-queued
> +
> +This will also rebuild a new drm-intel-nightly integration tree. If that fails,
> +ask maintainers for help with resolving conflicts. One thing to note here is
> +that the script syncs saved git rerere conflict resolutions around. One does the
> +resolution, everyone has it. The drawback is, someone screws up the conflict
> +resolution, everyone has it...
> +
> +Note that every two weeks Daniel cuts a new drm-intel-next by tagging what's in
> +drm-intel-next-queued. To increase the chances that the tree isn't totally
> +broken, only push bug fixes for serious problems on Thu/Fri (and weekend) every
> +second week (at the moment the release cycle is aligned with odd work weeks, but
> +just check out when the last tagged happened).
> +
> +If you need to push something to drm-intel-fixes or
> +drm-intel-next-fixes, please quickly coordinate with Jani.
> +
>  CONTRIBUTING
>  ============

-- 
Jani Nikula, Intel Open Source Technology Center