linux-next: manual merge of the sound tree with the jc_docs tree

linux-next: manual merge of the sound tree with the jc_docs tree

[Stephen Rothwell]

Hi Takashi,

Today's linux-next merge of the sound tree got a conflict in:

  Documentation/index.rst

between commits:

  799a545bb938 ("tpm: move documentation under Documentation/security")
  ba42c574fc8b ("Documentation: Add HOWTO Korean translation into rst based build system")

from the jc_docs tree and commit:

  8551914a5e19 ("ALSA: doc: ReSTize alsa-driver-api document")

from the sound tree.

I fixed it up (see below) and can carry the fix as necessary. This
is now fixed as far as linux-next is concerned, but any non trivial
conflicts should be mentioned to your upstream maintainer when your tree
is submitted for merging.  You may also want to consider cooperating
with the maintainer of the conflicting tree to minimise any particularly
complex conflicts.

-- 
Cheers,
Stephen Rothwell

diff --cc Documentation/index.rst
index 733bd9013541,115c551da5f5..000000000000
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@@ -57,16 -18,8 +57,17 @@@ needed)
     media/index
     gpu/index
     80211/index
 +   security/index
+    sound/index
  
 +Korean translations
 +-------------------
 +
 +.. toctree::
 +   :maxdepth: 1
 +
 +   translations/ko_KR/index
 +
  Indices and tables
  ==================
  

Re: linux-next: manual merge of the sound tree with the jc_docs tree

[Jonathan Corbet]

On Mon, 14 Nov 2016 11:15:53 +1100
Stephen Rothwell <sfr@canb.auug.org.au> wrote:

> Today's linux-next merge of the sound tree got a conflict in:
> 
>   Documentation/index.rst
> 
> between commits:
> 
>   799a545bb938 ("tpm: move documentation under Documentation/security")
>   ba42c574fc8b ("Documentation: Add HOWTO Korean translation into rst based build system")
> 
> from the jc_docs tree and commit:
> 
>   8551914a5e19 ("ALSA: doc: ReSTize alsa-driver-api document")
> 
> from the sound tree.

Sigh.  I'm glad this work is being done, but if we're going to create
some coordinated documentation it might be good to involve the docs
maintainer when doing it...

In this case, I would have liked the chance to comment.  This
documentation belongs in the driver-api document, not the top-level one.
So, in an ideal world, I'd like to see this stuff moved there, preferably
with the patches going though the docs tree.

(Thanks, Stephen, for fixing it up).

jon

Re: linux-next: manual merge of the sound tree with the jc_docs tree

[Takashi Iwai]

On Mon, 14 Nov 2016 01:56:28 +0100,
Jonathan Corbet wrote:
> 
> On Mon, 14 Nov 2016 11:15:53 +1100
> Stephen Rothwell <sfr@canb.auug.org.au> wrote:
> 
> > Today's linux-next merge of the sound tree got a conflict in:
> > 
> >   Documentation/index.rst
> > 
> > between commits:
> > 
> >   799a545bb938 ("tpm: move documentation under Documentation/security")
> >   ba42c574fc8b ("Documentation: Add HOWTO Korean translation into rst based build system")
> > 
> > from the jc_docs tree and commit:
> > 
> >   8551914a5e19 ("ALSA: doc: ReSTize alsa-driver-api document")
> > 
> > from the sound tree.
> 
> Sigh.  I'm glad this work is being done, but if we're going to create
> some coordinated documentation it might be good to involve the docs
> maintainer when doing it...

Sorry, will put you guys in Cc at the next time (although all
conversions have been done in the sound tree).

> In this case, I would have liked the chance to comment.  This
> documentation belongs in the driver-api document, not the top-level one.
> So, in an ideal world, I'd like to see this stuff moved there, preferably
> with the patches going though the docs tree.

If there needs any other changes, feel free to merge my
topic/restize-docs branch into yours and keep working there:
  git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git topic/resize-docs

It's based on vanilla 4.9-rc4, so it must be clean to be merged.  A
few misc fixes will come up in for-next branch, but they should be
harmless to your changes -- at least the api-related changes won't be
touched.


thanks,

Takashi

> 
> (Thanks, Stephen, for fixing it up).
> 
> jon
> 

Re: linux-next: manual merge of the sound tree with the jc_docs tree

[Jonathan Corbet]

On Mon, 14 Nov 2016 09:01:13 +0100
Takashi Iwai <tiwai@suse.de> wrote:

> > Sigh.  I'm glad this work is being done, but if we're going to create
> > some coordinated documentation it might be good to involve the docs
> > maintainer when doing it...  
> 
> Sorry, will put you guys in Cc at the next time (although all
> conversions have been done in the sound tree).

That's kind of my point.  The sound tree is not an appropriate place to be
making changes to files like Documentation/index.rst.

> > In this case, I would have liked the chance to comment.  This
> > documentation belongs in the driver-api document, not the top-level
> > one. So, in an ideal world, I'd like to see this stuff moved there,
> > preferably with the patches going though the docs tree.  
> 
> If there needs any other changes, feel free to merge my
> topic/restize-docs branch into yours and keep working there:
>   git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git
> topic/resize-docs
> 
> It's based on vanilla 4.9-rc4, so it must be clean to be merged.  A
> few misc fixes will come up in for-next branch, but they should be
> harmless to your changes -- at least the api-related changes won't be
> touched.

OK, I'll probably do that; expect me to run a patch by you that moves it
to the proper place in the hierarchy.

Thanks,

jon

Re: linux-next: manual merge of the sound tree with the jc_docs tree

[Takashi Iwai]

On Mon, 14 Nov 2016 17:11:59 +0100,
Jonathan Corbet wrote:
> 
> On Mon, 14 Nov 2016 09:01:13 +0100
> Takashi Iwai <tiwai@suse.de> wrote:
> 
> > > Sigh.  I'm glad this work is being done, but if we're going to create
> > > some coordinated documentation it might be good to involve the docs
> > > maintainer when doing it...  
> > 
> > Sorry, will put you guys in Cc at the next time (although all
> > conversions have been done in the sound tree).
> 
> That's kind of my point.  The sound tree is not an appropriate place to be
> making changes to files like Documentation/index.rst.

Well, I meant just that I have *finished* all conversions in sound :)

> > > In this case, I would have liked the chance to comment.  This
> > > documentation belongs in the driver-api document, not the top-level
> > > one. So, in an ideal world, I'd like to see this stuff moved there,
> > > preferably with the patches going though the docs tree.  
> > 
> > If there needs any other changes, feel free to merge my
> > topic/restize-docs branch into yours and keep working there:
> >   git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git
> > topic/resize-docs
> > 
> > It's based on vanilla 4.9-rc4, so it must be clean to be merged.  A
> > few misc fixes will come up in for-next branch, but they should be
> > harmless to your changes -- at least the api-related changes won't be
> > touched.
> 
> OK, I'll probably do that; expect me to run a patch by you that moves it
> to the proper place in the hierarchy.

Great, thanks.


Takashi

Re: linux-next: manual merge of the sound tree with the jc_docs tree

[Jonathan Corbet]

On Mon, 14 Nov 2016 09:01:13 +0100
Takashi Iwai <tiwai@suse.de> wrote:

> > In this case, I would have liked the chance to comment.  This
> > documentation belongs in the driver-api document, not the top-level one.
> > So, in an ideal world, I'd like to see this stuff moved there, preferably
> > with the patches going though the docs tree.  
> 
> If there needs any other changes, feel free to merge my
> topic/restize-docs branch into yours and keep working there:
>   git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git topic/resize-docs

OK, I've done that, so this series will show up in docs-next; hopefully
the merge conflicts will be resolved in the process.

I had said that I really wanted to move it all under driver-api and put
it into that manual, but, looking at what's there, it's not that simple.
The driver API parts of that manual belong there, but some of the
information is user-oriented.  A long-term goal is to separate out those
two types of information so that interested readers can more easily find
the information relevant to them.  But that won't happen for 4.10..:)  So
I'll leave things as they are for now.

(Note also that the driver API manual already has a section on sound
devices:

	http://static.lwn.net/kerneldoc/driver-api/sound.html

This came from the driver DocBook conversion a while back.  At some point
we should really pull all that stuff together into a single document).

Thanks again for doing this conversion,

jon

Re: linux-next: manual merge of the sound tree with the jc_docs tree

[Jarkko Sakkinen]

On Fri, Nov 18, 2016 at 04:33:12PM -0700, Jonathan Corbet wrote:
> On Mon, 14 Nov 2016 09:01:13 +0100
> Takashi Iwai <tiwai@suse.de> wrote:
> 
> > > In this case, I would have liked the chance to comment.  This
> > > documentation belongs in the driver-api document, not the top-level one.
> > > So, in an ideal world, I'd like to see this stuff moved there, preferably
> > > with the patches going though the docs tree.  
> > 
> > If there needs any other changes, feel free to merge my
> > topic/restize-docs branch into yours and keep working there:
> >   git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git topic/resize-docs
> 
> OK, I've done that, so this series will show up in docs-next; hopefully
> the merge conflicts will be resolved in the process.
> 
> I had said that I really wanted to move it all under driver-api and put
> it into that manual, but, looking at what's there, it's not that simple.
> The driver API parts of that manual belong there, but some of the
> information is user-oriented.  A long-term goal is to separate out those
> two types of information so that interested readers can more easily find
> the information relevant to them.  But that won't happen for 4.10..:)  So
> I'll leave things as they are for now.
> 
> (Note also that the driver API manual already has a section on sound
> devices:
> 
> 	http://static.lwn.net/kerneldoc/driver-api/sound.html
> 
> This came from the driver DocBook conversion a while back.  At some point
> we should really pull all that stuff together into a single document).
> 
> Thanks again for doing this conversion,
> 
> jon

Given that there is now a directory for TPM rst documentation do you
still want all changes to your tree or is it sufficient to just cc
linux-doc?

Thanks for fixing the issues!

/Jarkko

Re: linux-next: manual merge of the sound tree with the jc_docs tree

[Jonathan Corbet]

On Fri, 18 Nov 2016 16:22:18 -0800
Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> wrote:

> Given that there is now a directory for TPM rst documentation do you
> still want all changes to your tree or is it sufficient to just cc
> linux-doc?

For stuff in security/tpm?  It makes my life easier if documentation
patches come through my tree, but it's never going to be the case that
they all take that path.  I'm becoming increasingly insistent that changes
to the top-level makefiles and index.rst files need to come this way;
that way, Stephen doesn't need to send me so many polite merge-conflict
emails :)

For the rest, a CC is appreciated so that I know what's going on, but if
it works better for subsystem-specific documentation patches to go
through the relevant subsystem trees, then that's how it should be done.

Thanks,

jon

linux-next: manual merge of the sound tree with the jc_docs tree

[Stephen Rothwell]

Hi Takashi,

Today's linux-next merge of the sound tree got a conflict in:

  Documentation/sound/alsa/alsa-parameters.txt

between commit:

  8c27ceff3604 ("docs: fix locations of several documents that got moved")

from the jc_docs tree and commit:

  3a5182c04a02 ("ALSA: doc: Remove alsa-parameters.txt")

from the sound tree.

I fixed it up (I just removed the file) and can carry the fix as
necessary. This is now fixed as far as linux-next is concerned, but any
non trivial conflicts should be mentioned to your upstream maintainer
when your tree is submitted for merging.  You may also want to consider
cooperating with the maintainer of the conflicting tree to minimise any
particularly complex conflicts.

-- 
Cheers,
Stephen Rothwell