From: Dan Williams <dan.j.williams@intel.com>
To: mchehab+samsung@kernel.org
Cc: Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
Dave Jiang <dave.jiang@intel.com>,
ksummit <ksummit-discuss@lists.linuxfoundation.org>,
linux-nvdimm <linux-nvdimm@lists.01.org>,
Vishal L Verma <vishal.l.verma@intel.com>,
zwisler@kernel.org
Subject: Re: [Ksummit-discuss] [RFC PATCH 3/3] libnvdimm, MAINTAINERS: Subsystem Profile
Date: Fri, 16 Nov 2018 11:20:49 -0800 [thread overview]
Message-ID: <CAPcyv4gySBHp=-xnwA7f10K2wDuqPAB2C8C=9uU0q_mXcnzxbw@mail.gmail.com> (raw)
In-Reply-To: <20181115063040.11eaef93@silica.lan>
On Thu, Nov 15, 2018 at 6:31 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Em Wed, 14 Nov 2018 20:53:30 -0800
> Dan Williams <dan.j.williams@intel.com> escreveu:
>
> > Document the basic policies of the libnvdimm subsystem and provide a
> > first example of a Subsystem Profile for others to duplicate and edit.
> >
> > Cc: Ross Zwisler <zwisler@kernel.org>
> > 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/subsystem-profile.rst | 86 ++++++++++++++++++++++++++++
> > MAINTAINERS | 4 +
> > 2 files changed, 90 insertions(+)
> > create mode 100644 Documentation/nvdimm/subsystem-profile.rst
> >
> > diff --git a/Documentation/nvdimm/subsystem-profile.rst b/Documentation/nvdimm/subsystem-profile.rst
> > new file mode 100644
> > index 000000000000..d3428be7528e
> > --- /dev/null
> > +++ b/Documentation/nvdimm/subsystem-profile.rst
>
> Hmm... would it make sense to add a pointer at maintainer/index.rst (or to some
> other .rst file) for those profiles too?
>
> > @@ -0,0 +1,86 @@
> > +LIBNVDIMM Subsystem Profile
> > +===========================
> > +
> > +Overview
> > +--------
>
> A minor nitpick here: I would add a blank line after each topic/subtopic.
>
> On some cases, Sphinx will do wrong without that blank line, and having
> some places with that extra line and others without it sounds unbalanced
> on my eyes ;-)
>
> > +So, you have recently become a maintainer of the LIBNVDIMM subsystem,
> > +condolences, it is a thankless job, here is the lay of the land. The git
>
> My understanding that the main focus of this document is to help people to
> submit patches to the subsystem.
>
> With that in mind, I would never start the doc talking only to maintainers,
> as developers will likely just stop reading it at the above paragraph.
Yes, I see this is confusing now. I'll fix up the Subsystem Profile
description text to be written with maintainers as the audience and
clarify that the per-subsystem instance is written with contributors
as the audience.
>
> > +tree, git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git/, is
> > +writable by all the individuals listed in LIBNVDIMM section of
> > +MAINTAINERS. Access is granted per the typical kernel.org account
> > +management policies. Two branches in that tree are regularly pulled into
> > +-next, libnvdimm-for-next, and libnvdimm-fixes. The submit rate of
> > +patches is low, usually enough for one person to handle. There is a
> > +patchwork instance at
> > +https://patchwork.kernel.org/project/linux-nvdimm/list/, and it
> > +historically is only used for ingesting patches and collecting
> > +ack/review tags, i.e. no expectation to update the patch state after it
> > +has been dispositioned, or merged.
> > +
> > +The most sensitive code area is the ACPI DSM (Device Specific Method)
> > +path. In addition to the general fragility of an ioctl() ABI the ACPI
> > +DSM scheme allows any vendor to implement any command without any prior
> > +review by the ACPI committee. For this reason the LIBNVDIMM system seeks
> > +to constrain the proliferation of vendor commands and at a minimum
> > +requires any command support to be publicly documented. Over time the
> > +submission rate of new vendor-specific commands is falling as more
> > +commands are defined with named methods in the official ACPI
> > +specification.
>
> As Jani pointed, all the above stuff is for maintainers, but several other
> stuff on this document are for developers. The best would likely to have
> two separate files.
>
> However, maintaining it on two separate files could be painful. Maybe
> we could have an specific section, at the end of the document, with
> maintainers-specific instructions.
Yes, good idea, will incorporate.
next prev parent reply other threads:[~2018-11-16 19:21 UTC|newest]
Thread overview: 61+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-11-15 4:53 [RFC PATCH 0/3] Maintainer Handbook: Subsystem Profile Dan Williams
2018-11-15 4:53 ` [RFC PATCH 1/3] MAINTAINERS: Reclaim the P: tag for " Dan Williams
2018-11-15 5:39 ` [Ksummit-discuss] " Mauro Carvalho Chehab
2018-11-15 20:12 ` Joe Perches
2018-11-15 4:53 ` [RFC PATCH 2/3] MAINTAINERS, Handbook: " Dan Williams
2018-11-15 5:48 ` [Ksummit-discuss] " Julia Lawall
2018-11-15 7:59 ` Geert Uytterhoeven
2018-11-15 13:47 ` Julia Lawall
2018-11-16 12:44 ` Jani Nikula
2018-11-16 17:56 ` Joe Perches
2018-11-17 14:12 ` Rob Herring
2018-11-17 17:03 ` Julia Lawall
2018-11-20 7:28 ` Jani Nikula
2018-11-15 5:49 ` Mauro Carvalho Chehab
2018-11-15 7:58 ` Geert Uytterhoeven
2018-11-15 8:38 ` Jani Nikula
2018-11-15 18:03 ` Tim.Bird
2018-11-15 23:56 ` Tobin C. Harding
2018-11-15 15:44 ` Mauro Carvalho Chehab
2018-11-16 23:28 ` Randy Dunlap
2018-11-17 11:57 ` Hans Verkuil
2018-11-16 0:11 ` Frank Rowand
2018-11-16 12:04 ` Mauro Carvalho Chehab
2018-11-16 18:57 ` Dan Williams
2018-11-18 12:58 ` Mauro Carvalho Chehab
2018-11-18 17:31 ` Dan Williams
2018-11-18 17:31 ` Dan Williams
2018-11-18 17:34 ` Dan Williams
2018-11-18 17:44 ` Mauro Carvalho Chehab
2018-11-16 16:47 ` Frank Rowand
2018-11-15 4:53 ` [RFC PATCH 3/3] libnvdimm, MAINTAINERS: " Dan Williams
2018-11-15 8:03 ` [Ksummit-discuss] " Geert Uytterhoeven
2018-11-15 14:10 ` Mauro Carvalho Chehab
2018-11-15 16:20 ` Leon Romanovsky
2018-11-15 19:09 ` Mauro Carvalho Chehab
2018-11-15 19:35 ` Leon Romanovsky
2018-11-15 19:40 ` Luck, Tony
2018-11-15 19:43 ` Joe Perches
2018-11-16 11:39 ` Mauro Carvalho Chehab
2018-11-18 7:12 ` Leon Romanovsky
2018-11-16 11:33 ` Mauro Carvalho Chehab
2018-11-16 12:00 ` Jan Kara
2018-11-18 7:00 ` Leon Romanovsky
2018-11-16 20:36 ` Rodrigo Vivi
2018-11-16 23:44 ` Dan Williams
2018-11-17 0:38 ` NeilBrown
2018-11-18 13:11 ` Mauro Carvalho Chehab
2018-11-18 13:03 ` Mauro Carvalho Chehab
2018-11-20 8:10 ` Jani Nikula
2018-11-20 19:31 ` Dan Williams
2018-11-26 11:12 ` Mauro Carvalho Chehab
2018-11-26 15:55 ` Joe Perches
2018-11-16 19:13 ` Dan Williams
2018-11-15 14:30 ` Mauro Carvalho Chehab
2018-11-15 14:51 ` Julia Lawall
2018-11-16 19:20 ` Dan Williams [this message]
2018-11-16 2:58 ` y-goto
2018-11-17 0:32 ` [Ksummit-discuss] " David Woodhouse
2018-11-15 5:56 ` [RFC PATCH 0/3] Maintainer Handbook: " Mauro Carvalho Chehab
2018-11-25 10:57 ` Pavel Machek
2018-11-25 20:55 ` Dan Williams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAPcyv4gySBHp=-xnwA7f10K2wDuqPAB2C8C=9uU0q_mXcnzxbw@mail.gmail.com' \
--to=dan.j.williams@intel.com \
--cc=dave.jiang@intel.com \
--cc=ksummit-discuss@lists.linuxfoundation.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-nvdimm@lists.01.org \
--cc=mchehab+samsung@kernel.org \
--cc=vishal.l.verma@intel.com \
--cc=zwisler@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).