[Intel-gfx] [PATCH] drm-intel: add notes about handling -nightly rebuilds

[Jani Nikula]

Nitpick, should have [maintainer-tools PATCH] in the subject.

On Wed, 13 Jan 2016, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> Also try to polish the formatting a bit.
>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
>  drm-intel.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 59 insertions(+), 1 deletion(-)
>
> diff --git a/drm-intel.rst b/drm-intel.rst
> index 12bceb4e5324..e5c54d3d64ed 100644
> --- a/drm-intel.rst
> +++ b/drm-intel.rst
> @@ -167,7 +167,7 @@ or, if the fix is relevant for a released kernel,
>  If your patch fixes a regression then please include a Fixes: line to help
>  maintainers where to cherry-pick a patch to. This also extremely useful for
>  product groups to know which bugfixes they must include. To follow the
> -recommended format please generate the Fixes: line using
> +recommended format please generate the Fixes: line using ::
>  
>          $ dim fixes $regressing_commit
>  
> @@ -208,6 +208,64 @@ Signed-off-by: line in the commit message:
>  
>  	(cherry picked from commit 0bff4858653312a10c83709e0009c3adb87e6f1e)
>  
> +Resolving Conflicts when Rebuilding drm-intel-nightly
> +=====================================================

Starting to wonder where the line is between putting stuff in dim.rst
and drm-intel.rst. This is borderline. I kind of thought of
drm-intel.rst as the high level view (also think managers) into the
process, while dim.rst covers the details with using the tool. Anyway,
easy to move back and forth as needed, so not a big deal.

> +
> +When you push patches with dim drm-intel-nightly always gets rebuild and this
> +can sometimes fail, for example like this: ::
> +
> +        Updating rerere cache and nightly.conf... Done.
> +        Fetching drm-upstream... Done.
> +        Fetching origin... Done.
> +        Fetching sound-upstream... Done.
> +        Merging origin/drm-intel-fixes... Reset. Done.
> +        Merging drm-upstream/drm-fixes... Fast-forward. Done.
> +        Merging origin/drm-intel-next-fixes... Done.
> +        Merging origin/drm-intel-next-queued... ++<<<<<<< HEAD
> +        ++=======
> +        ++>>>>>>> origin/drm-intel-next-queued
> +        Fail: conflict merging origin/drm-intel-next-queued
> +
> +Often it's very easy to resolve such conflicts, but maintainers can take over
> +when it's tricky or something fails in the below procedure.
> +
> +1. First check that drm-intel-next-queued was indeed pushed correctly and that
> +   your local and remote branches match.
> +
> +2. Then re-run the -nightly generation just to confirm: ::
> +
> +        $ dim rebuild-nightly
> +
> +   It's handy to keep the log output for context so that you know which branch
> +   caused the conflicts, and which branches are already included.
> +
> +3. Switch to $DIM_SRC/drm-intel-nightly and analyze the conflict: ::

\$DIM_PREFIX ?

> +
> +        $ git diff # shows three-way diff of conflict
> +        $ gitk --merge # lists all commits git believes to be relevant
> +
> +   If the conflict is simple and created by one of the patches fix things up and
> +   compile/test the resulting kernel. In case of doubt just ping authors of
> +   other patches or maintainers on IRC.
> +
> +4. When you're happy with the resolution commit it with ::
> +
> +        $ git commit -a
> +
> +   git will then store the conflict resolution internally (see git help rerere
> +   for how this is implemented). Then re-run -nigthly generation to confirm the
> +   resolution has been captured correctly by git (sometimes git rerere can't
> +   match up your resolution with the conflict for odd reasons) and to make sure

Hmm, does this require the user has rerere.enabled=true in .gitconfig?

> +   there's no other conflict in later merges: ::
> +
> +        $ dim rebuild-nightly
> +
> +   This will also push the stored conflict resolution to the drm-intel-rerere
> +   branch and therefore publishes your resolution. Everything before this step
> +   has just local effects.

It can not be emphasized enough that this is not your average conflict
resolution where by breaking it you shoot yourself in the foot. Our
maintainer tools will helpfully shoot all the other developers in the
feet as well.

What's the procedure for throwing away the local rerere cache before you
rebuild-nightly? Is 'dim ub' enough?


> +
> +And if any step fails or the conflict is tricky just ping maintainers.
> +
>  Merge Timeline
>  ==============

-- 
Jani Nikula, Intel Open Source Technology Center