Linux-NVDIMM Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH v3 0/3] Maintainer Entry Profiles
@ 2019-11-24 20:59 Dan Williams
  2019-11-24 20:59 ` [PATCH v3 1/3] MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile Dan Williams
                   ` (3 more replies)
  0 siblings, 4 replies; 7+ messages in thread
From: Dan Williams @ 2019-11-24 20:59 UTC (permalink / raw)
  To: corbet
  Cc: Mauro Carvalho Chehab, Daniel Vetter, Linus Torvalds,
	Dmitry Vyukov, Thomas Gleixner, Joe Perches, Tobin C. Harding,
	Alexandre Belloni, Greg Kroah-Hartman, Steve French,
	Olof Johansson, Paul Walmsley, linux-kernel, linux-nvdimm,
	linux-doc

Changes since v2 [1]:
- Drop any consideration for coding style concerns in the profile. It
  was a minor aspect of the proposal that generated the bulk of the
  feedback on v2. Lets make progress on the rest.

- Clarify that the "Submit Checklist Addendum" can also include details
  that submitters need to take into account before even beginning to
  craft a patch. This is in response to the RISC-V use case of
  declaring specification readiness as a patch gate, and is now also used
  by the libnvdimm subsystem to clarify details about ACPI NVDIMM Device
  Specific Method specifications. (Paul)

- Non-change from v2: Kees had asked for a common directory for all
  profiles to live, but Mauro noted that this could be handled later
  with some scripting to post-process the MAINTAINERS file, or otherwise
  converting MAINTAINERS to ReST.

- Clarify the cover letter to focus on the contributor focused
  Maintainer Entry Profiles, and defer discussion of a maintainer
  focused Handbook.

[1]: https://lore.kernel.org/ksummit-discuss/156821692280.2951081.18036584954940423225.stgit@dwillia2-desk3.amr.corp.intel.com/

---

At last years Plumbers Conference I proposed the Maintainer Entry
Profile as a document that a maintainer can provide to set contributor
expectations and provide fodder for a discussion between maintainers
about the merits of different maintainer policies.

For those that did not attend, the goal of the Maintainer Entry Profile
is to provide contributors documentation of patch submission
considerations that may vary by subsystem. The session introduction was:

    The first rule of kernel maintenance is that there are no hard and
    fast rules. That state of affairs is both a blessing and a curse. It
    has served the community well to be adaptable to the different
    people and different problem spaces that inhabit the kernel
    community. However, that variability also leads to inconsistent
    experiences for contributors, little to no guidance for new
    contributors, and unnecessary stress on current maintainers.

To be clear, the proposed document does not impose or suggest new rules.
Instead it provides an outlet to document the existing unwritten
policies in effect for a given subsystem.  Over time the hope is that
some of this variability can be up-levelled to new global process
policy, but in the meantime it provides relief for communicating the
guidelines that are being imposed on contributors.

---

Dan Williams (3):
      MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile
      Maintainer Handbook: Maintainer Entry Profile
      libnvdimm, MAINTAINERS: Maintainer Entry Profile


 Documentation/maintainer/index.rst                 |    1 
 .../maintainer/maintainer-entry-profile.rst        |   87 ++++++++++++++++++++
 Documentation/nvdimm/maintainer-entry-profile.rst  |   59 ++++++++++++++
 MAINTAINERS                                        |   20 +++--
 4 files changed, 158 insertions(+), 9 deletions(-)
 create mode 100644 Documentation/maintainer/maintainer-entry-profile.rst
 create mode 100644 Documentation/nvdimm/maintainer-entry-profile.rst
_______________________________________________
Linux-nvdimm mailing list -- linux-nvdimm@lists.01.org
To unsubscribe send an email to linux-nvdimm-leave@lists.01.org

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH v3 1/3] MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile
  2019-11-24 20:59 [PATCH v3 0/3] Maintainer Entry Profiles Dan Williams
@ 2019-11-24 20:59 ` Dan Williams
  2019-11-24 20:59 ` [PATCH v3 2/3] Maintainer Handbook: " Dan Williams
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 7+ messages in thread
From: Dan Williams @ 2019-11-24 20:59 UTC (permalink / raw)
  To: corbet; +Cc: Joe Perches, linux-kernel, linux-nvdimm, linux-doc

Fixup some P: entries to be M: and delete the others that do not include an
email address. The P: tag will be used to indicate the location of a
Profile for a given MAINTAINERS entry.

Cc: Joe Perches <joe@perches.com>
Signed-off-by: Dan Williams <dan.j.williams@intel.com>
---
 MAINTAINERS |   12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index e7a47b5210fd..3f171339df53 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -76,7 +76,6 @@ trivial patch so apply some common sense.
 
 Descriptions of section entries:
 
-	P: Person (obsolete)
 	M: Mail patches to: FullName <address@domain>
 	R: Designated reviewer: FullName <address@domain>
 	   These reviewers should be CCed on patches.
@@ -811,7 +810,7 @@ S:	Orphan
 F:	drivers/usb/gadget/udc/amd5536udc.*
 
 AMD GEODE PROCESSOR/CHIPSET SUPPORT
-P:	Andres Salomon <dilinger@queued.net>
+M:	Andres Salomon <dilinger@queued.net>
 L:	linux-geode@lists.infradead.org (moderated for non-subscribers)
 W:	http://www.amd.com/us-en/ConnectivitySolutions/TechnicalResources/0,,50_2334_2452_11363,00.html
 S:	Supported
@@ -10085,7 +10084,6 @@ F:	drivers/staging/media/tegra-vde/
 
 MEDIA INPUT INFRASTRUCTURE (V4L/DVB)
 M:	Mauro Carvalho Chehab <mchehab@kernel.org>
-P:	LinuxTV.org Project
 L:	linux-media@vger.kernel.org
 W:	https://linuxtv.org
 Q:	http://patchwork.kernel.org/project/linux-media/list/
@@ -13452,7 +13450,6 @@ S:	Maintained
 F:	arch/mips/ralink
 
 RALINK RT2X00 WIRELESS LAN DRIVER
-P:	rt2x00 project
 M:	Stanislaw Gruszka <sgruszka@redhat.com>
 M:	Helmut Schaa <helmut.schaa@googlemail.com>
 L:	linux-wireless@vger.kernel.org
@@ -13787,7 +13784,6 @@ S:	Supported
 F:	drivers/net/ethernet/rocker/
 
 ROCKETPORT DRIVER
-P:	Comtrol Corp.
 W:	http://www.comtrol.com
 S:	Maintained
 F:	Documentation/driver-api/serial/rocket.rst
@@ -14668,15 +14664,13 @@ F:	drivers/video/fbdev/simplefb.c
 F:	include/linux/platform_data/simplefb.h
 
 SIMTEC EB110ATX (Chalice CATS)
-P:	Ben Dooks
-P:	Vincent Sanders <vince@simtec.co.uk>
+M:	Vincent Sanders <vince@simtec.co.uk>
 M:	Simtec Linux Team <linux@simtec.co.uk>
 W:	http://www.simtec.co.uk/products/EB110ATX/
 S:	Supported
 
 SIMTEC EB2410ITX (BAST)
-P:	Ben Dooks
-P:	Vincent Sanders <vince@simtec.co.uk>
+M:	Vincent Sanders <vince@simtec.co.uk>
 M:	Simtec Linux Team <linux@simtec.co.uk>
 W:	http://www.simtec.co.uk/products/EB2410ITX/
 S:	Supported
_______________________________________________
Linux-nvdimm mailing list -- linux-nvdimm@lists.01.org
To unsubscribe send an email to linux-nvdimm-leave@lists.01.org

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH v3 2/3] Maintainer Handbook: Maintainer Entry Profile
  2019-11-24 20:59 [PATCH v3 0/3] Maintainer Entry Profiles Dan Williams
  2019-11-24 20:59 ` [PATCH v3 1/3] MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile Dan Williams
@ 2019-11-24 20:59 ` " Dan Williams
  2019-11-24 20:59 ` [PATCH v3 3/3] libnvdimm, MAINTAINERS: " Dan Williams
  2019-11-25 15:50 ` [PATCH v3 0/3] Maintainer Entry Profiles Jonathan Corbet
  3 siblings, 0 replies; 7+ messages in thread
From: Dan Williams @ 2019-11-24 20:59 UTC (permalink / raw)
  To: corbet
  Cc: Thomas Gleixner, Mauro Carvalho Chehab, Steve French,
	Greg Kroah-Hartman, Linus Torvalds, Tobin C. Harding,
	Olof Johansson, Daniel Vetter, Joe Perches, Dmitry Vyukov,
	Alexandre Belloni, Paul Walmsley, linux-kernel, linux-nvdimm,
	linux-doc

As presented at the 2018 Linux Plumbers conference [1], the Maintainer
Entry Profile (formerly Subsystem Profile) is proposed as a way to reduce
friction between committers and maintainers and encourage conversations
amongst maintainers about common best practices. While coding-style,
submit-checklist, and submitting-drivers lay out some common expectations
there remain local customs and maintainer preferences that vary by
subsystem.

The profile contains documentation of some of the common policy
questions a contributor might have that are local to the subsystem /
device-driver, special considerations for the subsystem, or other
guidelines that are otherwise not covered by the top-level process
documents.

The initial and hopefully non-controversial headings in the profile are:

    Overview:
    General introduction to how the subsystem operates

    Submit Checklist Addendum:
    Mechanical items that gate submission staging, or other requirements
    that gate patch acceptance.

    Key Cycle Dates:
     - Last -rc for new feature submissions: Expected lead time for submissions
     - Last -rc to merge features: Deadline for merge decisions

    Resubmit Cadence: When and preferred method to follow up with the
    maintainer

Note that coding style guidelines are explicitly left out of this list.

See Documentation/maintainer/maintainer-entry-profile.rst for more details,
and a follow-on example profile for the libnvdimm subsystem.

[1]: https://linuxplumbersconf.org/event/2/contributions/59/

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Steve French <stfrench@microsoft.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Tobin C. Harding <me@tobin.cc>
Cc: Olof Johansson <olof@lixom.net>
Cc: Martin K. Petersen <martin.petersen@oracle.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Joe Perches <joe@perches.com>
Cc: Dmitry Vyukov <dvyukov@google.com>
Cc: Alexandre Belloni <alexandre.belloni@bootlin.com>
Cc: Paul Walmsley <paul.walmsley@sifive.com>
Signed-off-by: Dan Williams <dan.j.williams@intel.com>
---
 Documentation/maintainer/index.rst                 |    1 
 .../maintainer/maintainer-entry-profile.rst        |   87 ++++++++++++++++++++
 MAINTAINERS                                        |    4 +
 3 files changed, 92 insertions(+)
 create mode 100644 Documentation/maintainer/maintainer-entry-profile.rst

diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
index 56e2c09dfa39..d904e74e1159 100644
--- a/Documentation/maintainer/index.rst
+++ b/Documentation/maintainer/index.rst
@@ -12,4 +12,5 @@ additions to this manual.
    configure-git
    rebasing-and-merging
    pull-requests
+   maintainer-entry-profile
 
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
new file mode 100644
index 000000000000..51de3b9e606d
--- /dev/null
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -0,0 +1,87 @@
+.. _maintainerentryprofile:
+
+Maintainer Entry Profile
+========================
+
+The Maintainer Entry Profile supplements the top-level process documents
+(submitting-patches, submitting drivers...) with
+subsystem/device-driver-local customs as well as details about the patch
+submission life-cycle. A contributor uses this document to level set
+their expectations and avoid common mistakes, maintainers may use these
+profiles to look across subsystems for opportunities to converge on
+common practices.
+
+
+Overview
+--------
+Provide an introduction to how the subsystem operates. While MAINTAINERS
+tells the contributor where to send patches for which files, it does not
+convey other subsystem-local infrastructure and mechanisms that aid
+development.
+Example questions to consider:
+- Are there notifications when patches are applied to the local tree, or
+  merged upstream?
+- Does the subsystem have a patchwork instance? Are patchwork state
+  changes notified?
+- Any bots or CI infrastructure that watches the list, or automated
+  testing feedback that the subsystem gates acceptance?
+- Git branches that are pulled into -next?
+- What branch should contributors submit against?
+- Links to any other Maintainer Entry Profiles? For example a
+  device-driver may point to an entry for its parent subsystem. This makes
+  the contributor aware of obligations a maintainer may have have for
+  other maintainers in the submission chain.
+
+
+Submit Checklist Addendum
+-------------------------
+List mandatory and advisory criteria, beyond the common "submit-checklist",
+for a patch to be considered healthy enough for maintainer attention.
+For example: "pass checkpatch.pl with no errors, or warning. Pass the
+unit test detailed at $URI".
+
+The Submit Checklist Addendum can also include details about the status
+of related hardware specifications. For example, does the subsystem
+require published specifications at a certain revision before patches
+will be considered.
+
+
+Key Cycle Dates
+---------------
+One of the common misunderstandings of submitters is that patches can be
+sent at any time before the merge window closes and can still be
+considered for the next -rc1. The reality is that most patches need to
+be settled in soaking in linux-next in advance of the merge window
+opening. Clarify for the submitter the key dates (in terms rc release
+week) that patches might considered for merging and when patches need to
+wait for the next -rc. At a minimum:
+- Last -rc for new feature submissions:
+  New feature submissions targeting the next merge window should have
+  their first posting for consideration before this point. Patches that
+  are submitted after this point should be clear that they are targeting
+  the NEXT+1 merge window, or should come with sufficient justification
+  why they should be considered on an expedited schedule. A general
+  guideline is to set expectation with contributors that new feature
+  submissions should appear before -rc5.
+
+- Last -rc to merge features: Deadline for merge decisions
+  Indicate to contributors the point at which an as yet un-applied patch
+  set will need to wait for the NEXT+1 merge window. Of course there is no
+  obligation to ever except any given patchset, but if the review has not
+  concluded by this point the expectation the contributor should wait and
+  resubmit for the following merge window.
+
+Optional:
+- First -rc at which the development baseline branch, listed in the
+  overview section, should be considered ready for new submissions.
+
+
+Review Cadence
+--------------
+One of the largest sources of contributor angst is how soon to ping
+after a patchset has been posted without receiving any feedback. In
+addition to specifying how long to wait before a resubmission this
+section can also indicate a preferred style of update like, resend the
+full series, or privately send a reminder email. This section might also
+list how review works for this code area and methods to get feedback
+that are not directly from the maintainer.
diff --git a/MAINTAINERS b/MAINTAINERS
index 3f171339df53..e5d111a86e61 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -98,6 +98,10 @@ Descriptions of section entries:
 	   Obsolete:	Old code. Something tagged obsolete generally means
 			it has been replaced by a better system and you
 			should be using that.
+	P: Subsystem Profile document for more details submitting
+	   patches to the given subsystem. This is either an in-tree file,
+	   or a URI. See Documentation/maintainer/maintainer-entry-profile.rst
+	   for details.
 	F: Files and directories with wildcard patterns.
 	   A trailing slash includes all files and subdirectory files.
 	   F:	drivers/net/	all files in and below drivers/net
_______________________________________________
Linux-nvdimm mailing list -- linux-nvdimm@lists.01.org
To unsubscribe send an email to linux-nvdimm-leave@lists.01.org

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH v3 3/3] libnvdimm, MAINTAINERS: Maintainer Entry Profile
  2019-11-24 20:59 [PATCH v3 0/3] Maintainer Entry Profiles Dan Williams
  2019-11-24 20:59 ` [PATCH v3 1/3] MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile Dan Williams
  2019-11-24 20:59 ` [PATCH v3 2/3] Maintainer Handbook: " Dan Williams
@ 2019-11-24 20:59 ` " Dan Williams
  2019-11-25 15:50 ` [PATCH v3 0/3] Maintainer Entry Profiles Jonathan Corbet
  3 siblings, 0 replies; 7+ messages in thread
From: Dan Williams @ 2019-11-24 20:59 UTC (permalink / raw)
  To: corbet; +Cc: linux-kernel, linux-nvdimm, linux-doc

Document the basic policies of the libnvdimm subsystem and provide a first
example of a Maintainer Entry Profile for others to duplicate and edit.

Cc: Vishal Verma <vishal.l.verma@intel.com>
Cc: Dave Jiang <dave.jiang@intel.com>
Signed-off-by: Dan Williams <dan.j.williams@intel.com>
---
 Documentation/nvdimm/maintainer-entry-profile.rst |   59 +++++++++++++++++++++
 MAINTAINERS                                       |    4 +
 2 files changed, 63 insertions(+)
 create mode 100644 Documentation/nvdimm/maintainer-entry-profile.rst

diff --git a/Documentation/nvdimm/maintainer-entry-profile.rst b/Documentation/nvdimm/maintainer-entry-profile.rst
new file mode 100644
index 000000000000..77081fd9be95
--- /dev/null
+++ b/Documentation/nvdimm/maintainer-entry-profile.rst
@@ -0,0 +1,59 @@
+LIBNVDIMM Maintainer Entry Profile
+==================================
+
+Overview
+--------
+The libnvdimm subsystem manages persistent memory across multiple
+architectures. The mailing list, is tracked by patchwork here:
+https://patchwork.kernel.org/project/linux-nvdimm/list/
+...and that instance is configured to give feedback to submitters on
+patch acceptance and upstream merge. Patches are merged to either the
+'libnvdimm-fixes', or 'libnvdimm-for-next' branch. Those branches are
+available here:
+https://git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git/
+
+In general patches can be submitted against the latest -rc, however if
+the incoming code change is dependent on other pending changes then the
+patch should be based on the libnvdimm-for-next branch. However, since
+persistent memory sits at the intersection of storage and memory there
+are cases where patches are more suitable to be merged through a
+Filesystem or the Memory Management tree. When in doubt copy the nvdimm
+list and the maintainers will help route.
+
+Submissions will be exposed to the kbuild robot for compile regression
+testing. It helps to get a success notification from that infrastructure
+before submitting, but it is not required.
+
+
+Submit Checklist Addendum
+-------------------------
+There are unit tests for the subsystem via the ndctl utility:
+https://github.com/pmem/ndctl
+Those tests need to be passed before the patches go upstream, but not
+necessarily before initial posting. Contact the list if you need help
+getting the test environment set up.
+
+### ACPI Device Specific Methods (_DSM)
+Before patches enabling for a new _DSM family will be considered it must
+be assigned a format-interface-code from the NVDIMM Sub-team of the ACPI
+Specification Working Group. In general, the stance of the subsystem is
+to push back on the proliferation of NVDIMM command sets, do strongly
+consider implementing support for an existing command set. See
+drivers/acpi/nfit/nfit.h for the set of support command sets.
+
+
+Key Cycle Dates
+---------------
+New submissions can be sent at any time, but if they intend to hit the
+next merge window they should be sent before -rc4, and ideally
+stabilized in the libnvdimm-for-next branch by -rc6. Of course if a
+patch set requires more than 2 weeks of review -rc4 is already too late
+and some patches may require multiple development cycles to review.
+
+
+Review Cadence
+--------------
+In general, please wait up to one week before pinging for feedback. A
+private mail reminder is preferred. Alternatively ask for other
+developers that have Reviewed-by tags for libnvdimm changes to take a
+look and offer their opinion.
diff --git a/MAINTAINERS b/MAINTAINERS
index e5d111a86e61..2be1e18a368e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9185,6 +9185,7 @@ M:	Dan Williams <dan.j.williams@intel.com>
 M:	Vishal Verma <vishal.l.verma@intel.com>
 M:	Dave Jiang <dave.jiang@intel.com>
 L:	linux-nvdimm@lists.01.org
+P:	Documentation/nvdimm/maintainer-entry-profile.rst
 Q:	https://patchwork.kernel.org/project/linux-nvdimm/list/
 S:	Supported
 F:	drivers/nvdimm/blk.c
@@ -9195,6 +9196,7 @@ M:	Vishal Verma <vishal.l.verma@intel.com>
 M:	Dan Williams <dan.j.williams@intel.com>
 M:	Dave Jiang <dave.jiang@intel.com>
 L:	linux-nvdimm@lists.01.org
+P:	Documentation/nvdimm/maintainer-entry-profile.rst
 Q:	https://patchwork.kernel.org/project/linux-nvdimm/list/
 S:	Supported
 F:	drivers/nvdimm/btt*
@@ -9204,6 +9206,7 @@ M:	Dan Williams <dan.j.williams@intel.com>
 M:	Vishal Verma <vishal.l.verma@intel.com>
 M:	Dave Jiang <dave.jiang@intel.com>
 L:	linux-nvdimm@lists.01.org
+P:	Documentation/nvdimm/maintainer-entry-profile.rst
 Q:	https://patchwork.kernel.org/project/linux-nvdimm/list/
 S:	Supported
 F:	drivers/nvdimm/pmem*
@@ -9223,6 +9226,7 @@ M:	Dave Jiang <dave.jiang@intel.com>
 M:	Keith Busch <keith.busch@intel.com>
 M:	Ira Weiny <ira.weiny@intel.com>
 L:	linux-nvdimm@lists.01.org
+P:	Documentation/nvdimm/maintainer-entry-profile.rst
 Q:	https://patchwork.kernel.org/project/linux-nvdimm/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git
 S:	Supported
_______________________________________________
Linux-nvdimm mailing list -- linux-nvdimm@lists.01.org
To unsubscribe send an email to linux-nvdimm-leave@lists.01.org

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v3 0/3] Maintainer Entry Profiles
  2019-11-24 20:59 [PATCH v3 0/3] Maintainer Entry Profiles Dan Williams
                   ` (2 preceding siblings ...)
  2019-11-24 20:59 ` [PATCH v3 3/3] libnvdimm, MAINTAINERS: " Dan Williams
@ 2019-11-25 15:50 ` Jonathan Corbet
  2019-11-25 16:41   ` Dan Williams
  3 siblings, 1 reply; 7+ messages in thread
From: Jonathan Corbet @ 2019-11-25 15:50 UTC (permalink / raw)
  To: Dan Williams
  Cc: Mauro Carvalho Chehab, Daniel Vetter, Linus Torvalds,
	Dmitry Vyukov, Thomas Gleixner, Joe Perches, Greg Kroah-Hartman,
	Steve French, Olof Johansson, Paul Walmsley, linux-kernel,
	linux-nvdimm, linux-doc

On Sun, 24 Nov 2019 12:59:42 -0800
Dan Williams <dan.j.williams@intel.com> wrote:

> Changes since v2 [1]:
> - Drop any consideration for coding style concerns in the profile. It
>   was a minor aspect of the proposal that generated the bulk of the
>   feedback on v2. Lets make progress on the rest.
> 
> - Clarify that the "Submit Checklist Addendum" can also include details
>   that submitters need to take into account before even beginning to
>   craft a patch. This is in response to the RISC-V use case of
>   declaring specification readiness as a patch gate, and is now also used
>   by the libnvdimm subsystem to clarify details about ACPI NVDIMM Device
>   Specific Method specifications. (Paul)
> 
> - Non-change from v2: Kees had asked for a common directory for all
>   profiles to live, but Mauro noted that this could be handled later
>   with some scripting to post-process the MAINTAINERS file, or otherwise
>   converting MAINTAINERS to ReST.
> 
> - Clarify the cover letter to focus on the contributor focused
>   Maintainer Entry Profiles, and defer discussion of a maintainer
>   focused Handbook.

OK, some notes...

I wish you'd done this against docs-next, that would have saved me
resolving a few conflicts on the MAINTAINERS file.

I thought we'd agreed to move this to the process book?  That said, I now
wonder about that...today I read the document as information for
maintainers on how to create their profile, so its location in the
maintainers manual is appropriate.

There were a number RST issues and warnings that I fixed up with the
following add-on patch; it was mostly a matter of adding blank lines where
needed.

One other warning resulted from the nvdimm profile document not being
linked into the TOC tree.  I've added a TOC section to the new document to
bring these things together for now.  This is almost certainly not what we
want in the longer term.

It was tempting to ask for this stuff to be fixed up, but I didn't want to
delay this work any longer.  So it's applied to docs-next; unless something
explodes in the very near future, I intend to push this for 5.5.

Thanks,

jon

From 0bfa52a43ec085c2f5eb2c35fcc6cf73bb802eae Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <corbet@lwn.net>
Date: Mon, 25 Nov 2019 08:42:12 -0700
Subject: [PATCH 2/2] docs: fix up the maintainer profile document

Add blank lines where needed to get the document to render properly.  Also
add a TOC of existing profiles just so that the nvdimm profile is linked
into the toctree, is discoverable, and doesn't generate a warning.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 .../maintainer/maintainer-entry-profile.rst       | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 51de3b9e606d..3eaddc8ac56d 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -18,7 +18,9 @@ Provide an introduction to how the subsystem operates. While MAINTAINERS
 tells the contributor where to send patches for which files, it does not
 convey other subsystem-local infrastructure and mechanisms that aid
 development.
+
 Example questions to consider:
+
 - Are there notifications when patches are applied to the local tree, or
   merged upstream?
 - Does the subsystem have a patchwork instance? Are patchwork state
@@ -55,6 +57,7 @@ be settled in soaking in linux-next in advance of the merge window
 opening. Clarify for the submitter the key dates (in terms rc release
 week) that patches might considered for merging and when patches need to
 wait for the next -rc. At a minimum:
+
 - Last -rc for new feature submissions:
   New feature submissions targeting the next merge window should have
   their first posting for consideration before this point. Patches that
@@ -72,6 +75,7 @@ wait for the next -rc. At a minimum:
   resubmit for the following merge window.
 
 Optional:
+
 - First -rc at which the development baseline branch, listed in the
   overview section, should be considered ready for new submissions.
 
@@ -85,3 +89,14 @@ section can also indicate a preferred style of update like, resend the
 full series, or privately send a reminder email. This section might also
 list how review works for this code area and methods to get feedback
 that are not directly from the maintainer.
+
+Existing profiles
+-----------------
+
+For now, existing maintainer profiles are listed here; we will likely want
+to do something different in the near future.
+
+.. toctree::
+   :maxdepth: 1
+
+   ../nvdimm/maintainer-entry-profile
-- 
2.21.0
_______________________________________________
Linux-nvdimm mailing list -- linux-nvdimm@lists.01.org
To unsubscribe send an email to linux-nvdimm-leave@lists.01.org

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v3 0/3] Maintainer Entry Profiles
  2019-11-25 15:50 ` [PATCH v3 0/3] Maintainer Entry Profiles Jonathan Corbet
@ 2019-11-25 16:41   ` Dan Williams
  2019-11-25 16:51     ` Jonathan Corbet
  0 siblings, 1 reply; 7+ messages in thread
From: Dan Williams @ 2019-11-25 16:41 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Mauro Carvalho Chehab, Daniel Vetter, Linus Torvalds,
	Dmitry Vyukov, Thomas Gleixner, Joe Perches, Tobin C. Harding,
	Alexandre Belloni, Greg Kroah-Hartman, Steve French,
	Olof Johansson, Paul Walmsley, Linux Kernel Mailing List,
	linux-nvdimm, Linux Doc Mailing List

On Mon, Nov 25, 2019 at 7:51 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> On Sun, 24 Nov 2019 12:59:42 -0800
> Dan Williams <dan.j.williams@intel.com> wrote:
>
> > Changes since v2 [1]:
> > - Drop any consideration for coding style concerns in the profile. It
> >   was a minor aspect of the proposal that generated the bulk of the
> >   feedback on v2. Lets make progress on the rest.
> >
> > - Clarify that the "Submit Checklist Addendum" can also include details
> >   that submitters need to take into account before even beginning to
> >   craft a patch. This is in response to the RISC-V use case of
> >   declaring specification readiness as a patch gate, and is now also used
> >   by the libnvdimm subsystem to clarify details about ACPI NVDIMM Device
> >   Specific Method specifications. (Paul)
> >
> > - Non-change from v2: Kees had asked for a common directory for all
> >   profiles to live, but Mauro noted that this could be handled later
> >   with some scripting to post-process the MAINTAINERS file, or otherwise
> >   converting MAINTAINERS to ReST.
> >
> > - Clarify the cover letter to focus on the contributor focused
> >   Maintainer Entry Profiles, and defer discussion of a maintainer
> >   focused Handbook.
>
> OK, some notes...
>
> I wish you'd done this against docs-next, that would have saved me
> resolving a few conflicts on the MAINTAINERS file.
>
> I thought we'd agreed to move this to the process book?  That said, I now
> wonder about that...today I read the document as information for
> maintainers on how to create their profile, so its location in the
> maintainers manual is appropriate.
>
> There were a number RST issues and warnings that I fixed up with the
> following add-on patch; it was mostly a matter of adding blank lines where
> needed.
>
> One other warning resulted from the nvdimm profile document not being
> linked into the TOC tree.  I've added a TOC section to the new document to
> bring these things together for now.  This is almost certainly not what we
> want in the longer term.
>
> It was tempting to ask for this stuff to be fixed up, but I didn't want to
> delay this work any longer.  So it's applied to docs-next; unless something
> explodes in the very near future, I intend to push this for 5.5.

Apologies for all of the above. I rushed it without considering the
docs submission basics. Thanks for moving this forward.
_______________________________________________
Linux-nvdimm mailing list -- linux-nvdimm@lists.01.org
To unsubscribe send an email to linux-nvdimm-leave@lists.01.org

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v3 0/3] Maintainer Entry Profiles
  2019-11-25 16:41   ` Dan Williams
@ 2019-11-25 16:51     ` Jonathan Corbet
  0 siblings, 0 replies; 7+ messages in thread
From: Jonathan Corbet @ 2019-11-25 16:51 UTC (permalink / raw)
  To: Dan Williams
  Cc: Mauro Carvalho Chehab, Daniel Vetter, Linus Torvalds,
	Dmitry Vyukov, Thomas Gleixner, Joe Perches, Greg Kroah-Hartman,
	Steve French, Olof Johansson, Paul Walmsley,
	Linux Kernel Mailing List, linux-nvdimm, Linux Doc Mailing List

On Mon, 25 Nov 2019 08:41:16 -0800
Dan Williams <dan.j.williams@intel.com> wrote:

> Apologies for all of the above. I rushed it without considering the
> docs submission basics. Thanks for moving this forward.

That's OK, I don't have a maintainer profile for you to refer to yet :)

Thanks,

jon
_______________________________________________
Linux-nvdimm mailing list -- linux-nvdimm@lists.01.org
To unsubscribe send an email to linux-nvdimm-leave@lists.01.org

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, back to index

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-11-24 20:59 [PATCH v3 0/3] Maintainer Entry Profiles Dan Williams
2019-11-24 20:59 ` [PATCH v3 1/3] MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile Dan Williams
2019-11-24 20:59 ` [PATCH v3 2/3] Maintainer Handbook: " Dan Williams
2019-11-24 20:59 ` [PATCH v3 3/3] libnvdimm, MAINTAINERS: " Dan Williams
2019-11-25 15:50 ` [PATCH v3 0/3] Maintainer Entry Profiles Jonathan Corbet
2019-11-25 16:41   ` Dan Williams
2019-11-25 16:51     ` Jonathan Corbet

Linux-NVDIMM Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-nvdimm/0 linux-nvdimm/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-nvdimm linux-nvdimm/ https://lore.kernel.org/linux-nvdimm \
		linux-nvdimm@lists.01.org
	public-inbox-index linux-nvdimm

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.01.lists.linux-nvdimm


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git