[PATCH] doc: add a separate page for drm-tip
Jani Nikula
jani.nikula at intel.com
Thu Apr 26 14:43:31 UTC 2018
On Thu, 26 Apr 2018, Daniel Vetter <daniel at ffwll.ch> wrote:
> 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>
Pushed, thanks for the review.
BR,
Jani.
>> ---
>> 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
--
Jani Nikula, Intel Open Source Technology Center
More information about the dim-tools
mailing list