| Message ID | 20211209003833.6396-1-ebiggers@kernel.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | docs: consolidate sysfs-block into Documentation/ABI/ | expand |
On Wed, Dec 08, 2021 at 04:38:25PM -0800, Eric Biggers wrote: > This series consolidates the documentation for /sys/block/<disk>/queue/ > into Documentation/ABI/, where it is supposed to go (as per Greg KH: > https://lore.kernel.org/r/YaXXpEAwVGTLjp1e@kroah.com). > > This series also updates MAINTAINERS to associate the block > documentation with the block layer. > > This series applies to linux-block/for-next. > > Changed v2 => v3: > - Improved documentation for stable_writes and virt_boundary_mask. > - Added more Reviewed-by tags. > > Changed v1 => v2: > - Added patch which moves the documentation to the stable directory. > - Added Reviewed-by tags. Jens, any interest in applying this series? - Eric
On Tue, Dec 21, 2021 at 09:41:47AM -0600, Eric Biggers wrote: > On Wed, Dec 08, 2021 at 04:38:25PM -0800, Eric Biggers wrote: > > This series consolidates the documentation for /sys/block/<disk>/queue/ > > into Documentation/ABI/, where it is supposed to go (as per Greg KH: > > https://lore.kernel.org/r/YaXXpEAwVGTLjp1e@kroah.com). > > > > This series also updates MAINTAINERS to associate the block > > documentation with the block layer. > > > > This series applies to linux-block/for-next. > > > > Changed v2 => v3: > > - Improved documentation for stable_writes and virt_boundary_mask. > > - Added more Reviewed-by tags. > > > > Changed v1 => v2: > > - Added patch which moves the documentation to the stable directory. > > - Added Reviewed-by tags. > > Jens, any interest in applying this series? > > - Eric Ping.
On Mon, Jan 03, 2022 at 09:06:18AM -0600, Eric Biggers wrote: > On Tue, Dec 21, 2021 at 09:41:47AM -0600, Eric Biggers wrote: > > On Wed, Dec 08, 2021 at 04:38:25PM -0800, Eric Biggers wrote: > > > This series consolidates the documentation for /sys/block/<disk>/queue/ > > > into Documentation/ABI/, where it is supposed to go (as per Greg KH: > > > https://lore.kernel.org/r/YaXXpEAwVGTLjp1e@kroah.com). > > > > > > This series also updates MAINTAINERS to associate the block > > > documentation with the block layer. > > > > > > This series applies to linux-block/for-next. > > > > > > Changed v2 => v3: > > > - Improved documentation for stable_writes and virt_boundary_mask. > > > - Added more Reviewed-by tags. > > > > > > Changed v1 => v2: > > > - Added patch which moves the documentation to the stable directory. > > > - Added Reviewed-by tags. > > > > Jens, any interest in applying this series? > > > > - Eric > > Ping. Jens, any reason you haven't applied this series yet? It looks like you've been applying other patches. To be clear, I've been expecting that this would go in through the block tree, rather than the docs tree. - Eric
On 1/6/22 13:41, Eric Biggers wrote: > Jens, any reason you haven't applied this series yet? It looks like you've been > applying other patches. To be clear, I've been expecting that this would go in > through the block tree, rather than the docs tree. We are close to the v5.17 merge window so this is not a good time for a maintainer to apply a large patch series. If Jens does not reply I propose to repost this patch series after the v5.17 merge window has closed (three weeks from now?). See also https://lore.kernel.org/lkml/CAHk-=wg=3dEpPGhz8YvJUDWhFW_GUeASBGmqyw3aPQRfB3ki9w@mail.gmail.com/ Thanks, Bart.
On 1/7/22 1:58 PM, Bart Van Assche wrote: > On 1/6/22 13:41, Eric Biggers wrote: >> Jens, any reason you haven't applied this series yet? It looks like you've been >> applying other patches. To be clear, I've been expecting that this would go in >> through the block tree, rather than the docs tree. > > We are close to the v5.17 merge window so this is not a good time for a maintainer to > apply a large patch series. If Jens does not reply I propose to repost this patch > series after the v5.17 merge window has closed (three weeks from now?). I'm fine with it, but it should probably just go through the doc tree.
On Sun, Jan 09, 2022 at 10:01:11AM -0700, Jens Axboe wrote: > On 1/7/22 1:58 PM, Bart Van Assche wrote: > > On 1/6/22 13:41, Eric Biggers wrote: > >> Jens, any reason you haven't applied this series yet? It looks like you've been > >> applying other patches. To be clear, I've been expecting that this would go in > >> through the block tree, rather than the docs tree. > > > > We are close to the v5.17 merge window so this is not a good time for a maintainer to > > apply a large patch series. If Jens does not reply I propose to repost this patch > > series after the v5.17 merge window has closed (three weeks from now?). > > I'm fine with it, but it should probably just go through the doc tree. I think it makes much more sense for subsystems to be responsible for their own documentation; that's why patch 8 in this series adds the block layer documentation to the block layer MAINTAINERS entry. Do you disagree with that? - Eric
On 1/9/22 2:25 PM, Eric Biggers wrote: > On Sun, Jan 09, 2022 at 10:01:11AM -0700, Jens Axboe wrote: >> On 1/7/22 1:58 PM, Bart Van Assche wrote: >>> On 1/6/22 13:41, Eric Biggers wrote: >>>> Jens, any reason you haven't applied this series yet? It looks like you've been >>>> applying other patches. To be clear, I've been expecting that this would go in >>>> through the block tree, rather than the docs tree. >>> >>> We are close to the v5.17 merge window so this is not a good time for a maintainer to >>> apply a large patch series. If Jens does not reply I propose to repost this patch >>> series after the v5.17 merge window has closed (three weeks from now?). >> >> I'm fine with it, but it should probably just go through the doc tree. > > I think it makes much more sense for subsystems to be responsible for > their own documentation; that's why patch 8 in this series adds the > block layer documentation to the block layer MAINTAINERS entry. Do > you disagree with that? I agree, but then we often end up with merge conflicts between the doc tree and others. That's why it's usually punted there. As a maintainer, any conflicts is a pain in the butt to deal with, something the contributor doesn't necessarily see or understand. If there are no conflicts this time around, I can queue them up.
On Wed, 8 Dec 2021 16:38:25 -0800, Eric Biggers wrote: > This series consolidates the documentation for /sys/block/<disk>/queue/ > into Documentation/ABI/, where it is supposed to go (as per Greg KH: > https://lore.kernel.org/r/YaXXpEAwVGTLjp1e@kroah.com). > > This series also updates MAINTAINERS to associate the block > documentation with the block layer. > > [...] Applied, thanks! [1/8] docs: sysfs-block: move to stable directory commit: ae7a7a53498f452eb927cd4b4eed0bccded85ebf [2/8] docs: sysfs-block: sort alphabetically commit: 07c9093c429361dd405499b1e433e4170b81551f [3/8] docs: sysfs-block: add contact for nomerges commit: 8b0551a74b4a9396a7f6ddb0c5f6f3c8465e9d45 [4/8] docs: sysfs-block: fill in missing documentation from queue-sysfs.rst commit: 849ab826e10531f106846e8e9eeae8d00a198f6e [5/8] docs: sysfs-block: document stable_writes commit: 1163010418a7f0c60c309743498cb6c5cd828ecc [6/8] docs: sysfs-block: document virt_boundary_mask commit: 8bc2f7c67061cb39e317a45ad9870f529b1fb190 [7/8] docs: block: remove queue-sysfs.rst commit: 208e4f9c0028e9181220460600b1df0bc677e796 [8/8] MAINTAINERS: add entries for block layer documentation commit: f029cedb9bb5bab7f1bb3042be348f2dac0ee66e Best regards,
Jens Axboe <axboe@kernel.dk> writes: > On 1/9/22 2:25 PM, Eric Biggers wrote: >> I think it makes much more sense for subsystems to be responsible for >> their own documentation; that's why patch 8 in this series adds the >> block layer documentation to the block layer MAINTAINERS entry. Do >> you disagree with that? > > I agree, but then we often end up with merge conflicts between the doc > tree and others. That's why it's usually punted there. As a maintainer, > any conflicts is a pain in the butt to deal with, something the > contributor doesn't necessarily see or understand. > > If there are no conflicts this time around, I can queue them up. [Docs maintainer not copied on any of this, but you can't escape :)] Maintaining docs is a bit of a challenge for the reason Jens mentions: everybody puts their fingers into it, and the result is lots of merge conflicts. For that reason, I'd prefer that big changes go through the docs tree. Changes to directories like Documentation/ABI can be especially prone to conflicts, FWIW. I also tend to be a bit more attentive to things like the addition of docs-build warnings than maintainers from other subsystems. That said, the real goal is to get more and better documentation merged, and it often does make the most sense for docs changes to go through other trees. Forcing the separation of documentation changes from the code changes they reflect would be kind of silly at best, for example. So if the block tree is the best path for these changes, then all I can say is: Acked-by: Jonathan Corbet <corbet@lwn.net> Thanks, jon