Re: [PATCH net-next v2 5/6] bonding: update Documentation for port/bond terminology

From: Andrew Lunn
Date: Fri Oct 02 2020 - 14:09:17 EST


On Fri, Oct 02, 2020 at 01:40:00PM -0400, Jarod Wilson wrote:
> Point users to the new interface names instead of the old ones, where
> appropriate. Userspace bits referenced still include use of master/slave,
> but those can't be altered until userspace changes too, ideally after
> these changes propagate to the community at large.
>
> Cc: Jay Vosburgh <j.vosburgh@xxxxxxxxx>
> Cc: Veaceslav Falico <vfalico@xxxxxxxxx>
> Cc: Andy Gospodarek <andy@xxxxxxxxxxxxx>
> Cc: "David S. Miller" <davem@xxxxxxxxxxxxx>
> Cc: Jakub Kicinski <kuba@xxxxxxxxxx>
> Cc: Thomas Davis <tadavis@xxxxxxx>
> Cc: netdev@xxxxxxxxxxxxxxx
> Signed-off-by: Jarod Wilson <jarod@xxxxxxxxxx>
> ---
> Documentation/networking/bonding.rst | 440 +++++++++++++--------------
> 1 file changed, 220 insertions(+), 220 deletions(-)
>
> diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst
> index adc314639085..f4c4f0fae83b 100644
> --- a/Documentation/networking/bonding.rst
> +++ b/Documentation/networking/bonding.rst
> @@ -167,22 +167,22 @@ or, for backwards compatibility, the option value. E.g.,
>
> The parameters are as follows:
>
> -active_slave
> +active_port

Hi Jarod

It is going to take quite a while before all distributions user space
gets updated. So todays API is going to live on for a few
years. People are going to be search the documentation using the terms
their user space uses, which are going to be todays terms, not the new
ones you are introducing here. For that to work, i think you are going
to have to introduce a table listing todays names and the new names
you are adding, so search engines have some chance of finding this
document, and readers have some clue as to how to translate from what
their user space is using to the terms used in the document.

Andrew