[PATCH] doc: add a separate page for drm-tip
Daniel Vetter
daniel at ffwll.ch
Thu Apr 26 14:07:28 UTC 2018
On Thu, Apr 26, 2018 at 04:27:53PM +0300, Jani Nikula wrote:
> Describe drm-tip and move conflict resolution guidance there. Add some
> relevant cross-references, as well as update the drm-misc maintainers
> while at it.
>
> Signed-off-by: Jani Nikula <jani.nikula at intel.com>
Yeah, well overdue we pull this out.
On both patches: Reviewed-by: Daniel Vetter <daniel.vetter at ffwll.ch>
> ---
> drm-intel.rst | 94 +--------------------------------------------
> drm-misc.rst | 2 +
> drm-tip.rst | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> index.rst | 1 +
> repositories.rst | 21 ++++++-----
> 5 files changed, 129 insertions(+), 102 deletions(-)
> create mode 100644 drm-tip.rst
>
> diff --git a/drm-intel.rst b/drm-intel.rst
> index d3362b244ebe..c68949a41c95 100644
> --- a/drm-intel.rst
> +++ b/drm-intel.rst
> @@ -1,3 +1,5 @@
> +.. _drm-intel:
> +
> ===========
> drm-intel
> ===========
> @@ -109,98 +111,6 @@ Signed-off-by: line in the commit message:
>
> (cherry picked from commit 0bff4858653312a10c83709e0009c3adb87e6f1e)
>
> -Resolving Conflicts when Rebuilding drm-tip
> -===========================================
> -
> -When you push patches with dim drm-tip always gets rebuilt 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 rebuild the integration branch just to confirm: ::
> -
> - $ dim rebuild-tip
> -
> - 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_PREFIX/drm-tip and analyze the conflict: ::
> -
> - $ cd $DIM_PREFIX/drm-tip
> - $ 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 you pushed 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 drm-tip 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
> - there's no other conflict in later merges: ::
> -
> - $ dim rebuild-tip
> -
> - 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.
> -
> -And if any step fails or the conflict is tricky just ping maintainers.
> -
> -If the Conflict Reappears
> --------------------------
> -
> -In some odd cases git rerere fails to recognize the conflict, and doesn't store
> -conflict resolution. This needs to be handled with a manual fixup patch, and the
> -best way to go about this is:
> -
> -1. Try to resolve the conflict normally, but then running ::
> -
> - $ dim rebuild-tip
> -
> - fails. First, store the current state, including the conflict markers and
> - with no other changes applied::
> -
> - $ cd $DIM_PREFIX/drm-tip
> - $ git add -u
> - $ git commit
> -
> -2. Resolve the conflict normally, but don't stage it or commit it in any
> - fashion. Check that the resolution looks correct and removes all the conflict
> - markers you've just committed::
> -
> - $ git diff
> -
> - Then store it as a manual fixup patch::
> -
> - $ git diff | dim cat-to-fixup
> -
> - And finally rebuild the integration tree, which should now go through
> - smoothly, at least for this merge::
> -
> - $ dim rebuild-tip
> -
> Merge Timeline
> ==============
>
> diff --git a/drm-misc.rst b/drm-misc.rst
> index a884e023048e..a0217bc78f1d 100644
> --- a/drm-misc.rst
> +++ b/drm-misc.rst
> @@ -1,3 +1,5 @@
> +.. _drm-misc:
> +
> =========
> drm-misc
> =========
> diff --git a/drm-tip.rst b/drm-tip.rst
> new file mode 100644
> index 000000000000..133ef1699b92
> --- /dev/null
> +++ b/drm-tip.rst
> @@ -0,0 +1,113 @@
> +.. _drm-tip:
> +
> +=========
> + drm-tip
> +=========
> +
> +The drm-tip branch (in the drm-tip repository) is the common DRM subsystem
> +testing and integration tree (or "pile" to complete the reverse acronym). It's a
> +bit like linux-next for graphics. It gets rebuilt every time one of the branches
> +maintained using dim is updated.
> +
> +It should be emphasized that no patch ever gets pushed to drm-tip directly,
> +drm-tip is not upstream per se, and no pull requests are ever sent to or from
> +drm-tip. It is, however, the merge result of a number of upstream branches like
> +that. It is the combined bleeding edge of kernel graphics.
> +
> +The drm-rerere branch contains the `nightly.conf`_ configuration file that
> +describes the branches that get merged to drm-tip, as well as shared conflict
> +resolution for merging the branches on drm-tip rebuild.
> +
> +.. _nightly.conf: https://cgit.freedesktop.org/drm/drm-tip/plain/nightly.conf?h=rerere-cache
> +
> +Resolving Conflicts when Rebuilding drm-tip
> +===========================================
> +
> +When you push patches with dim drm-tip always gets rebuilt 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 rebuild the integration branch just to confirm::
> +
> + $ dim rebuild-tip
> +
> + 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_PREFIX/drm-tip and analyze the conflict::
> +
> + $ cd $DIM_PREFIX/drm-tip
> + $ 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 you pushed 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 drm-tip 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
> + there's no other conflict in later merges::
> +
> + $ dim rebuild-tip
> +
> + 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.
> +
> +And if any step fails or the conflict is tricky just ping maintainers.
> +
> +If the Conflict Reappears
> +-------------------------
> +
> +In some odd cases git rerere fails to recognize the conflict, and doesn't store
> +conflict resolution. This needs to be handled with a manual fixup patch, and the
> +best way to go about this is:
> +
> +1. Try to resolve the conflict normally, but then running::
> +
> + $ dim rebuild-tip
> +
> + fails. First, store the current state, including the conflict markers and
> + with no other changes applied::
> +
> + $ cd $DIM_PREFIX/drm-tip
> + $ git add -u
> + $ git commit
> +
> +2. Resolve the conflict normally, but don't stage it or commit it in any
> + fashion. Check that the resolution looks correct and removes all the conflict
> + markers you've just committed::
> +
> + $ git diff
> +
> + Then store it as a manual fixup patch::
> +
> + $ git diff | dim cat-to-fixup
> +
> + And finally rebuild the integration tree, which should now go through
> + smoothly, at least for this merge::
> +
> + $ dim rebuild-tip
> diff --git a/index.rst b/index.rst
> index 3afece2ba817..d1fd4a14bde0 100644
> --- a/index.rst
> +++ b/index.rst
> @@ -23,6 +23,7 @@ Contents:
> :maxdepth: 2
>
> repositories
> + drm-tip
> drm-misc
> drm-intel
> getting-started
> diff --git a/repositories.rst b/repositories.rst
> index 1dbe84ca268d..44009656d5b2 100644
> --- a/repositories.rst
> +++ b/repositories.rst
> @@ -61,10 +61,11 @@ Linus' master on a weekly basis.
> The DRM Misc Repository
> -----------------------
>
> -See drm-misc_ for repository details. Maintained by Daniel Vetter, Gustavo
> -Padovan, and Sean Paul, with a large pool of committers.
> +See :ref:`drm-misc` and `the drm-misc repository`_ for repository
> +details. Maintained by Maarten Lankhorst, Gustavo Padovan, and Sean Paul, with a
> +large pool of committers.
>
> -.. _drm-misc: https://cgit.freedesktop.org/drm/drm-misc
> +.. _the drm-misc repository: https://cgit.freedesktop.org/drm/drm-misc
>
> drm-misc-next
> ~~~~~~~~~~~~~
> @@ -99,11 +100,11 @@ This is for bugfixes which target the current -rc cycle.
> The Upstream i915 Driver Repository
> -----------------------------------
>
> -See drm-intel_ for repository details. Maintained by Jani Nikula, Joonas
> -Lahtinen and Rodrigo Vivi, with a large pool of committers. Consists mostly of
> -``drivers/gpu/drm/i915``.
> +See :ref:`drm-intel` and `the drm-intel repository`_ for repository
> +details. Maintained by Jani Nikula, Joonas Lahtinen and Rodrigo Vivi, with a
> +large pool of committers. Consists mostly of ``drivers/gpu/drm/i915``.
>
> -.. _drm-intel: https://cgit.freedesktop.org/drm/drm-intel
> +.. _the drm-intel repository: https://cgit.freedesktop.org/drm/drm-intel
>
> drm-intel-next-queued (aka "dinq")
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -148,9 +149,9 @@ much follow the stable rules.
> The DRM Testing and Integration Repository
> ------------------------------------------
>
> -See drm-tip_ for repository details.
> +See :ref:`drm-tip` and `the drm-tip repository`_ for repository details.
>
> -.. _drm-tip: https://cgit.freedesktop.org/drm/drm-tip
> +.. _the drm-tip repository: https://cgit.freedesktop.org/drm/drm-tip
>
> drm-tip
> ~~~~~~~
> @@ -159,7 +160,7 @@ This is the overall integration tree for drm, and lives in
> ``git://anongit.freedesktop.org/drm-tip``. Every time one of the above branches
> is updated drm-tip gets rebuilt. If there's a conflict see section on `resolving
> conflicts when rebuilding drm-tip
> -<drm-intel.html#resolving-conflicts-when-rebuilding-drm-tip>`_.
> +<drm-tip.html#resolving-conflicts-when-rebuilding-drm-tip>`_.
>
> drm-rerere
> ~~~~~~~~~~
> --
> 2.11.0
>
> _______________________________________________
> dim-tools mailing list
> dim-tools at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dim-tools
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
More information about the dim-tools
mailing list