[v3] Documentation: subsystem-apis: Categorize remaining subsystems

  From: Bagas Sanjaya <bagasdotme@gmail.com>

Add classes:
* Core subsystems
* Storage
* Networking
* Peripherals and devices
* Embedded systems
* Integrity
* Virtualization
* Miscellaneous

There is a FIXME that says to organize subsystems listed in
subsystem-apis.rst. Fulfill it by categorize remaining subsytems
by purpose/themes, while sorting entries in each category.

HID devices are already categorized in 3c591cc954d56e ("docs:
consolidate human interface subsystems").

Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>

---

Changes:
v3: add Integrity, Virtualization and Miscellaneous per Bagas Sanjaya
v2: add Core subsystems, Networking, Peripherals and Embedded
v1: add Storgre category
---
 Documentation/subsystem-apis.rst | 119 ++++++++++++++++++++++---------
 1 file changed, 86 insertions(+), 33 deletions(-)
  

Hi--

On 6/1/23 07:55, Costa Shulyupin wrote:
> From: Bagas Sanjaya <bagasdotme@gmail.com>
> 
> Add classes:
> * Core subsystems
> * Storage
> * Networking
> * Peripherals and devices
> * Embedded systems
> * Integrity
> * Virtualization
> * Miscellaneous
> 
> There is a FIXME that says to organize subsystems listed in
> subsystem-apis.rst. Fulfill it by categorize remaining subsytems
> by purpose/themes, while sorting entries in each category.
> 
> HID devices are already categorized in 3c591cc954d56e ("docs:
> consolidate human interface subsystems").
> 
> Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>

This is a worthy goal, I am sure, but I am also sure that there is
a lot of bikeshedding that can go on here.
(examples below)

> 
> ---
> 
> Changes:
> v3: add Integrity, Virtualization and Miscellaneous per Bagas Sanjaya
> v2: add Core subsystems, Networking, Peripherals and Embedded
> v1: add Storgre category

          Storage

> ---
>  Documentation/subsystem-apis.rst | 119 ++++++++++++++++++++++---------
>  1 file changed, 86 insertions(+), 33 deletions(-)
> 
> diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
> index 55c90d5383ef..2c0b18a66e4e 100644
> --- a/Documentation/subsystem-apis.rst
> +++ b/Documentation/subsystem-apis.rst
> @@ -10,58 +10,111 @@ is taken directly from the kernel source, with supplemental material added
>  as needed (or at least as we managed to add it — probably *not* all that is
>  needed).
>  
> +Core subsystems
> +---------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   core-api/index
> +   cpu-freq/index
> +   driver-api/index
> +   locking/index
> +   mm/index
> +   power/index
> +   scheduler/index
> +   timers/index
> +   wmi/index
> +
>  Human interfaces
>  ----------------
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   input/index
> +   fb/index
> +   gpu/index
>     hid/index
> +   input/index
>     sound/index
> -   gpu/index
> -   fb/index
>  
> -**Fixme**: much more organizational work is needed here.
> +Storage
> +-------
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   driver-api/index
> -   core-api/index
> -   locking/index
> -   accounting/index
>     block/index
>     cdrom/index
> -   cpu-freq/index
> -   fpga/index
> -   i2c/index
> -   iio/index
> -   isdn/index
> +   filesystems/index
> +   pcmcia/index

Why is pcmcia in the storage category?
It's just an interface (or a bus).

> +   scsi/index

SCSI is also just a bus, but most (all?) of our drivers
are for storage controllers AFAIK, although I have seen
SCSI printer drivers, maybe even a SCSI toaster driver. :)

> +   target/index
> +
> +
> +Networking
> +----------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   bpf/index
>     infiniband/index
> -   leds/index
> +   isdn/index
> +   mhi/index
>     netlabel/index
>     networking/index
> -   pcmcia/index
> -   power/index
> -   target/index
> -   timers/index
> +
> +
> +Peripherals and devices
> +-----------------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   PCI/index
> +   hwmon/index
> +   leds/index
> +   misc-devices/index
> +   usb/index
> +
> +
> +Embedded systems
> +----------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   fpga/index
> +   i2c/index

I2C is just a bus IMO.
Same with SPI and W1.
Should we have a "Bus Interfaces" category?

> +   iio/index
> +   peci/index
>     spi/index
>     w1/index
> -   watchdog/index
> +
> +Integrity
> +---------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   crypto/index
> +   security/index
> +
> +Virtualization
> +--------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
>     virt/index
> -   hwmon/index
> +
> +Miscellaneous
> +-------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
>     accel/index
> -   security/index
> -   crypto/index
> -   filesystems/index
> -   mm/index
> -   bpf/index
> -   usb/index
> -   PCI/index
> -   scsi/index
> -   misc-devices/index
> -   scheduler/index
> -   mhi/index
> -   peci/index
> -   wmi/index
> +   accounting/index
> +   watchdog/index

Thanks.
  

On Thu, Jun 01, 2023 at 05:55:55PM +0300, Costa Shulyupin wrote:
> From: Bagas Sanjaya <bagasdotme@gmail.com>
> 
> Add classes:
> * Core subsystems
> * Storage
> * Networking
> * Peripherals and devices
> * Embedded systems
> * Integrity
> * Virtualization
> * Miscellaneous

Above list is unnecessary, because the diff should clearly show those
categories.

> 
> There is a FIXME that says to organize subsystems listed in
> subsystem-apis.rst. Fulfill it by categorize remaining subsytems
> by purpose/themes, while sorting entries in each category.
> 
> HID devices are already categorized in 3c591cc954d56e ("docs:
> consolidate human interface subsystems").
> 
> Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>

Thanks for picking my version from v2 [1]. However, From: address in the
patch message doesn't match one from message header nor your Signed-off-by
address. Conversely, if you handle someone else's patch (in this case mine),
you need to also add SoB from him/her.

As you're still newbie here, I'd recommend you to try contributing to
drivers/staging/ first in order to gain experience on kernel developement
workflow. Also, you use your RedHat address, so I expect you have been
given kernel development training from your company (and doesn't make
trivial errors like these ones).

Anyway, I'd like to send my own version instead (incorporating feedback
from this version) if you still reroll with trivial sending mistakes.

Thanks.

[1]: https://lore.kernel.org/linux-doc/ZHgM0qKWP3OusjUW@debian.me/
  

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> As you're still newbie here, I'd recommend you to try contributing to
> drivers/staging/ first in order to gain experience on kernel developement
> workflow. Also, you use your RedHat address, so I expect you have been
> given kernel development training from your company (and doesn't make
> trivial errors like these ones).

Bagas, please.  I'll ask you directly: please don't go telling
documentation contributors how to comport themselves; you have plenty
enough to learn yourself on that front.  It's hard enough to get
contributors to the documentation as it is without random people showing
up and giving orders.

I have distractions that are increasing my (already less than stellar)
latency, but I'll get to this stuff.

Thanks,

jon
  

On 6/2/23 17:19, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
>> As you're still newbie here, I'd recommend you to try contributing to
>> drivers/staging/ first in order to gain experience on kernel developement
>> workflow. Also, you use your RedHat address, so I expect you have been
>> given kernel development training from your company (and doesn't make
>> trivial errors like these ones).
> 
> Bagas, please.  I'll ask you directly: please don't go telling
> documentation contributors how to comport themselves; you have plenty
> enough to learn yourself on that front.  It's hard enough to get
> contributors to the documentation as it is without random people showing
> up and giving orders.
> 

Hi jon, thanks for another tip. I also learn contributing patches the
hard way by being rejected (honestly sometimes I learn, sometimes I
don't).

Let me clarify the situation. Previously in v2, I reviewed Costa's patch
by replying with proposing my own version, keeping patch author intact.
There, I categorized a few more items while sorting all of them. I
treated it as minor fixup that was attributed by brackets in the
SoB area (I could also use Co-developed-by: for this purpose too).
Then, Costa rerolled v3 using my version, but the From: address
in the patch message is mine without corresponding SoB, hence when you
apply his v3, there would be author mismatch (commit author is me
yet different SoB from him). I expected that my proposal in v2 is
carried by him (and also have SoB from both me and him as the sender
who carried my patch).

> I have distractions that are increasing my (already less than stellar)
> latency, but I'll get to this stuff.
> 

I'm too, because I'm AuDHD and I can (and do) easily distracted; living
in a paradox between routine fixation and desire for quick action :).

Thanks.
  

Costa Shulyupin <costa.shul@redhat.com> writes:

> From: Bagas Sanjaya <bagasdotme@gmail.com>
>
> Add classes:
> * Core subsystems
> * Storage
> * Networking
> * Peripherals and devices
> * Embedded systems
> * Integrity
> * Virtualization
> * Miscellaneous
>
> There is a FIXME that says to organize subsystems listed in
> subsystem-apis.rst. Fulfill it by categorize remaining subsytems
> by purpose/themes, while sorting entries in each category.
>
> HID devices are already categorized in 3c591cc954d56e ("docs:
> consolidate human interface subsystems").
>
> Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>

So now that I've found a moment to look at stuff, I'm a bit confused
here.  Up top, you have a From: line identifying Bagas as the author of
this patch - but it lacks his signoff so I can't apply it.

If this is *really* such a complex change that it needs a
co-developed-by tag, please arrange that and the correct signoffs.
Otherwise, please send a patch that's your work (which can certainly
reflect suggestions from others) that is properly tagged.

Thanks,

jon