Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Tue, 3 Mar 2020 18:07:02 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To:     Rob Herring <robh@kernel.org>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>,
        devicetree@vger.kernel.org
Subject: Re: [PATCH v2 00/12] Convert some DT documentation files to ReST
Message-ID: <20200303180702.677ba664@onda.lan>
In-Reply-To: <20200303180109.670ad7f8@onda.lan>
References: <cover.1583135507.git.mchehab+huawei@kernel.org>
        <20200302123554.08ac0c34@lwn.net>
        <20200303080947.5f381004@onda.lan>
        <CAL_JsqKsZNFDSsZJ+wzgD1Eaf0fBwZ7BeUv=32jAuE29TeRfnA@mail.gmail.com>
        <20200303180109.670ad7f8@onda.lan>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Em Tue, 3 Mar 2020 18:01:09 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Em Tue, 3 Mar 2020 10:20:25 -0600
> Rob Herring <robh@kernel.org> escreveu:
> 
> > On Tue, Mar 3, 2020 at 1:09 AM Mauro Carvalho Chehab
> > <mchehab+huawei@kernel.org> wrote:  
> > >
> > > Em Mon, 2 Mar 2020 12:35:54 -0700
> > > Jonathan Corbet <corbet@lwn.net> escreveu:
> > >    
> > > > On Mon,  2 Mar 2020 08:59:25 +0100
> > > > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > > >    
> > > > > While most of the devicetree stuff has its own format (with is now being
> > > > > converted to YAML format), some documents there are actually
> > > > > describing the DT concepts and how to contribute to it.
> > > > >
> > > > > IMHO, those documents would fit perfectly as part of the documentation
> > > > > body, as part of the firmare documents set.
> > > > >
> > > > > This patch series manually converts some DT documents that, on my
> > > > > opinion, would belong to it.    
> > > >
> > > > Did you consider putting this stuff into the firmware-guide while you were
> > > > at it?  It's not a perfect fit, I guess, but it doesn't seem too awkward
> > > > either.    
> > >
> > > I placed it just below the firmware-guide at the main index file.
> > >
> > > I have split thoughts about moving the files to there, though. From
> > > one side, it may fit better from the PoV of organizing the documentation.
> > >
> > > From other side, newcomers working with DT may expect looking at the
> > > text files inside Documentation/devicetree/.
> > >
> > > Maybe I could add an extra patch at the end of this series with the
> > > move, adding a "RFC" on his title. This way, we can better discuss it,
> > > and either merge the last one or not depending on the comments.    
> > 
> > Keep in mind that we generate a standalone DT only tree[1] with the
> > documentation, dts files and headers. So things should be structured
> > such that all the DT documentation could be built by itself without
> > dependencies on the 'kernel documentation'. I'm not asking for that to
> > be done in this series, but just don't do anything to make that
> > harder. I don't *think* have, but just want to make sure that's clear.  
> 
> So, I guess it is better to keep the .rst files under Documentation/devicetree,
> instead of moving them to Documentation/firmware-guide.
> 
> Well, if moved, I guess it would be easy to modify the scripts that produce
> the documentation to also parse something a new directory inside
> Documentation/firmware-guide.
> 
> >   
> > > > It also seems like it would be good to CC the devicetree folks, or at
> > > > least the devicetree mailing list?    
> > 
> > I was wondering what happened to the cover letter on v2...
> >   
> > > Yeah, that would make sense. I'm using get-maintainers script to
> > > prepare the c/c list, as it is simply too much work to find the
> > > right maintainers by hand, for every single patch.
> > >
> > > I just noticed today that there's just *one entry* at MAINTAINERS
> > > file for Documentation/devicetree, and that points to you:
> > >
> > >         DOCUMENTATION
> > >         M:      Jonathan Corbet <corbet@lwn.net>
> > >         L:      linux-doc@vger.kernel.org
> > >         S:      Maintained
> > >         F:      Documentation/
> > >         F:      scripts/documentation-file-ref-check
> > >         F:      scripts/kernel-doc
> > >         F:      scripts/sphinx-pre-install
> > >         X:      Documentation/ABI/
> > >         X:      Documentation/firmware-guide/acpi/
> > >         X:      Documentation/devicetree/    
> > 
> > You mean doesn't point to Jon as 'X' is exclude. You missed this entry:
> > 
> > OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
> > M:      Rob Herring <robh+dt@kernel.org>
> > M:      Mark Rutland <mark.rutland@arm.com>
> > L:      devicetree@vger.kernel.org
> > T:      git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git
> > Q:      http://patchwork.ozlabs.org/project/devicetree-bindings/list/
> > S:      Maintained
> > F:      Documentation/devicetree/
> > F:      arch/*/boot/dts/
> > F:      include/dt-bindings/  
> 
> Yeah, I remember I saw something like the above in the past. However,
> I'm not seeing this entry at the MAINTAINERS file at next-20200303 anymore.
> 
> Did someone removed such entry?

Sorry, false alarm. 

It is there at next. 

I guess it is time for call it a day.

That doesn't explain why I didn't add DT ML to the c/c. I'll try to 
verify what's going on tomorrow.

Regards,
Mauro