[PATCH 2/4] doc: extract repository documentation to a separate file

Mon Jan 29 19:43:44 UTC 2018

On Mon, Jan 29, 2018 at 02:28:53PM +0200, Jani Nikula wrote:
> Just the most basic extraction with minimal stylistic and content
> changes. Reference the new document from drm-intel and drm-misc
> documentation.

Again, we're missing drm-amd. Probably makes sense to volunteer Harry for the
description in a follow-on patch.

Reviewed-by: Sean Paul <seanpaul at chromium.org>

> 
> Signed-off-by: Jani Nikula <jani.nikula at intel.com>
> ---
>  drm-intel.rst    | 102 +----------------------------------
>  drm-misc.rst     |  42 +--------------
>  index.rst        |   1 +
>  repositories.rst | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  4 files changed, 165 insertions(+), 142 deletions(-)
>  create mode 100644 repositories.rst
> 
> diff --git a/drm-intel.rst b/drm-intel.rst
> index bf9a8c314f85..28d0895c88aa 100644
> --- a/drm-intel.rst
> +++ b/drm-intel.rst
> @@ -25,107 +25,7 @@ reality, it is your assumed responsibility to update the rules.
>  The Relevant Repositories and Branches
>  ======================================
>  
> -The Upstream Linux Kernel Repository
> -------------------------------------
> -
> -`git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git`
> -
> -Maintained by Linus Torvalds.
> -
> -master
> -~~~~~~
> -
> -Linus' master, the upstream, or mainline. This is where all features from all
> -subsystems, including DRM and i915, are merged.
> -
> -The upstream follows a single branch, time-based development model, with a new
> -kernel release occurring roughly every 10 weeks. New features are merged from
> -subsystem trees during the two week merge window immediately following a kernel
> -release. After the merge window, the new development kernel is stabilized by
> -only merging fixes until the next kernel release. During development, there's a
> -new release candidate (-rc) kernel each week.
> -
> -The Upstream DRM Subsystem Repository
> --------------------------------------
> -
> -`git://people.freedesktop.org/~airlied/linux.git`
> -
> -Maintained by Dave Airlie of Red Hat. Consists mostly of `drivers/gpu/drm`.
> -
> -drm-next
> -~~~~~~~~
> -
> -This is the branch where all new features for the DRM core and all the GPU
> -drivers, including drm/i915, are merged.
> -
> -The drm-next branch is closed for new features at around -rc5 timeframe of the
> -current development kernel in preparation for the upcoming merge window for the
> -next kernel, when drm-next gets merged to Linus' master. Thus there's a
> -stabilization period of about 3-5 weeks during which only bug fixes are merged
> -to drm-next.
> -
> -drm-fixes
> -~~~~~~~~~
> -
> -This is the branch where all the fixes for the DRM core and all the GPU drivers
> -for the current development kernels are merged. drm-fixes is usually merged to
> -Linus' master on a weekly basis.
> -
> -The Upstream i915 Driver Repository
> ------------------------------------
> -
> -`git://anongit.freedesktop.org/drm-intel`
> -
> -Maintained by Daniel Vetter and Jani Nikula, with several developers also having
> -commit access for pushing `drm-intel-next-queued`. Consists mostly of
> -`drivers/gpu/drm/i915`.
> -
> -drm-intel-next-queued (aka "dinq")
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -This is the branch where all new features, as well as any non-trivial or
> -controversial fixes, are applied.
> -
> -This branch "hides" the merge window from the drm/i915 developers; patches are
> -applied here regardless of the development phase of Linus' upstream kernel.
> -
> -drm-intel-next
> -~~~~~~~~~~~~~~
> -
> -drm-intel-next-queued at some point in time.
> -
> -drm-intel-next-fixes (aka "dinf")
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -This branch contains drm/i915 specific fixes to drm-next after the drm/i915
> -features have been merged there. Fixes are first applied to
> -drm-intel-next-queued, and cherry-picked to drm-intel-next-fixes.
> -
> -Pull requests to Dave are sent as needed, with no particular schedule.
> -
> -drm-intel-fixes (aka "-fixes")
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -This branch contains fixes to Linus' tree after drm-next has been merged during
> -the merge window. Fixes are first applied to drm-intel-next-queued, and
> -cherry-picked to drm-intel-fixes. The fixes are then merged through drm-fixes.
> -Valid from -rc1 to the kernel release.
> -
> -Usually Linus releases each -rc on a Sunday, and drm-intel-fixes gets rebased on
> -that the following Monday. Usually this is a fast-forward. The pull request to
> -Dave for new fixes is typically sent on the following Thursday. This is repeated
> -until final release of the kernel.
> -
> -This is the fastest path to getting fixes to Linus' tree. It is generally for
> -the regressions, cc:stable, black screens, GPU hangs only, and should pretty
> -much follow the stable rules.
> -
> -drm-tip
> -~~~~~~~
> -
> -This branch combines them all. Rebuilt every time one of the trees is pushed. It
> -is living in a separate git repository name
> -`drm-tip <https://cgit.freedesktop.org/drm-tip>`_.
> +See :ref:`repositories`.
>  
>  Patch and Merge Flow
>  ====================
> diff --git a/drm-misc.rst b/drm-misc.rst
> index c08234992266..187a4df07ad4 100644
> --- a/drm-misc.rst
> +++ b/drm-misc.rst
> @@ -31,47 +31,7 @@ guide.
>  Branches
>  ========
>  
> -All branches are maintained in `git://anongit.freedesktop.org/drm-misc`.
> -
> -drm-misc-next
> -~~~~~~~~~~~~~
> -
> -This is the main feature branch where most of the patches land. This branch is
> -always open to "hide" the merge window from developers. To avoid upsetting
> -linux-next and causing mayhem in the merge window, in general no pull requests
> -are sent to upstream after rc6 of the current kernel release. Outside of that
> -feature freeze period, pull requests are sent to upstream roughly every 1-2
> -weeks, to avoid too much coordination pains. See the timeline below for a
> -visualization of patch flow.
> -
> -If you're unsure, apply your patch here, it can always be cherry-picked to one
> -of the -fixes branches later on. But in contrast to the drm-intel flow
> -cherry-picking is not the default.
> -
> -drm-misc-next-fixes
> -~~~~~~~~~~~~~~~~~~~
> -
> -During the time between rc6 of kernel version X and rc1 of X+1,
> -drm-misc-next will be targeting kernel version X+2 and drm-misc-fixes
> -still targets kernel version X.  This branch is for fixes to bugs
> -introduced in the drm-misc-next pull request that was sent for X+1,
> -which aren't present in the drm-misc-fixes branch.
> -
> -See the timeline below for a visualization of patch flow.
> -
> -drm-misc-fixes
> -~~~~~~~~~~~~~~
> -
> -This is for bugfixes which target the current -rc cycle.
> -
> -drm-tip
> -~~~~~~~
> -
> -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>`_.
> +See :ref:`drm-misc-repository`.
>  
>  Where Do I Apply My Patch?
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~
> diff --git a/index.rst b/index.rst
> index 6110cc796d2a..ff5094802781 100644
> --- a/index.rst
> +++ b/index.rst
> @@ -22,6 +22,7 @@ Contents:
>  .. toctree::
>     :maxdepth: 2
>  
> +   repositories
>     drm-misc
>     drm-intel
>     dim
> diff --git a/repositories.rst b/repositories.rst
> new file mode 100644
> index 000000000000..a10ef934bced
> --- /dev/null
> +++ b/repositories.rst
> @@ -0,0 +1,162 @@
> +.. _repositories:
> +
> +===========================
> + Repositories and Branches
> +===========================
> +
> +All the relevant repositories and branches are described below. For the current
> +list of maintainers, mailing lists, etc. please refer to MAINTAINERS_.
> +
> +.. _MAINTAINERS: https://cgit.freedesktop.org/drm/drm-tip/plain/MAINTAINERS
> +
> +The Upstream Linux Kernel Repository
> +------------------------------------
> +
> +See upstream_ for repository details. Maintained by Linus Torvalds.
> +
> +.. _upstream: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/
> +
> +master
> +~~~~~~
> +
> +Linus' master, the upstream, or mainline. This is where all features from all
> +subsystems, including DRM and i915, are merged.
> +
> +The upstream follows a single branch, time-based development model, with a new
> +kernel release occurring roughly every 10 weeks. New features are merged from
> +subsystem trees during the two week merge window immediately following a kernel
> +release. After the merge window, the new development kernel is stabilized by
> +only merging fixes until the next kernel release. During development, there's a
> +new release candidate (-rc) kernel each week.
> +
> +The Upstream DRM Subsystem Repository
> +-------------------------------------
> +
> +See `drm upstream`_ for repository details. Maintained by Dave Airlie of Red
> +Hat. Consists mostly of ``drivers/gpu/drm`` and ``include/drm``.
> +
> +.. _drm upstream: https://cgit.freedesktop.org/~airlied/linux/
> +
> +drm-next
> +~~~~~~~~
> +
> +This is the branch where all new features for the DRM core and all the GPU
> +drivers, including drm/i915, are merged.
> +
> +The drm-next branch is closed for new features at around -rc5 timeframe of the
> +current development kernel in preparation for the upcoming merge window for the
> +next kernel, when drm-next gets merged to Linus' master. Thus there's a
> +stabilization period of about 3-5 weeks during which only bug fixes are merged
> +to drm-next.
> +
> +drm-fixes
> +~~~~~~~~~
> +
> +This is the branch where all the fixes for the DRM core and all the GPU drivers
> +for the current development kernels are merged. drm-fixes is usually merged to
> +Linus' master on a weekly basis.
> +
> +.. _drm-misc-repository:
> +
> +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.
> +
> +.. _drm-misc: https://cgit.freedesktop.org/drm/drm-tip
> +
> +drm-misc-next
> +~~~~~~~~~~~~~
> +
> +This is the main feature branch where most of the patches land. This branch is
> +always open to "hide" the merge window from developers. To avoid upsetting
> +linux-next and causing mayhem in the merge window, in general no pull requests
> +are sent to upstream after rc6 of the current kernel release. Outside of that
> +feature freeze period, pull requests are sent to upstream roughly every 1-2
> +weeks, to avoid too much coordination pains.
> +
> +If you're unsure, apply your patch here, it can always be cherry-picked to one
> +of the -fixes branches later on. But in contrast to the drm-intel flow
> +cherry-picking is not the default.
> +
> +drm-misc-next-fixes
> +~~~~~~~~~~~~~~~~~~~
> +
> +During the time between rc6 of kernel version X and rc1 of X+1, drm-misc-next
> +will be targeting kernel version X+2 and drm-misc-fixes still targets kernel
> +version X.  This branch is for fixes to bugs introduced in the drm-misc-next
> +pull request that was sent for X+1, which aren't present in the drm-misc-fixes
> +branch.
> +
> +drm-misc-fixes
> +~~~~~~~~~~~~~~
> +
> +This is for bugfixes which target the current -rc cycle.
> +
> +.. _drm-intel-repository:
> +
> +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``.
> +
> +.. _drm-intel: https://cgit.freedesktop.org/drm/drm-tip
> +
> +drm-intel-next-queued (aka "dinq")
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +This is the branch where all new features, as well as any non-trivial or
> +controversial fixes, are applied.
> +
> +This branch "hides" the merge window from the drm/i915 developers; patches are
> +applied here regardless of the development phase of Linus' upstream kernel.
> +
> +drm-intel-next
> +~~~~~~~~~~~~~~
> +
> +drm-intel-next-queued at some point in time.
> +
> +drm-intel-next-fixes (aka "dinf")
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +This branch contains drm/i915 specific fixes to drm-next after the drm/i915
> +features have been merged there. Fixes are first applied to
> +drm-intel-next-queued, and cherry-picked to drm-intel-next-fixes.
> +
> +Pull requests to Dave are sent as needed, with no particular schedule.
> +
> +drm-intel-fixes (aka "-fixes")
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +This branch contains fixes to Linus' tree after drm-next has been merged during
> +the merge window. Fixes are first applied to drm-intel-next-queued, and
> +cherry-picked to drm-intel-fixes. The fixes are then merged through drm-fixes.
> +Valid from -rc1 to the kernel release.
> +
> +Usually Linus releases each -rc on a Sunday, and drm-intel-fixes gets rebased on
> +that the following Monday. Usually this is a fast-forward. The pull request to
> +Dave for new fixes is typically sent on the following Thursday. This is repeated
> +until final release of the kernel.
> +
> +This is the fastest path to getting fixes to Linus' tree. It is generally for
> +the regressions, cc:stable, black screens, GPU hangs only, and should pretty
> +much follow the stable rules.
> +
> +The DRM Testing and Integration Repository
> +------------------------------------------
> +
> +See drm-tip_ for repository details.
> +
> +.. _drm-tip: https://cgit.freedesktop.org/drm/drm-tip
> +
> +drm-tip
> +~~~~~~~
> +
> +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>`_.
> -- 
> 2.11.0
> 
> _______________________________________________
> dim-tools mailing list
> dim-tools at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dim-tools

-- 
Sean Paul, Software Engineer, Google / Chromium OS