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

On Fri, Oct 2, 2020 at 2:09 PM Andrew Lunn [off-list ref] wrote:

On Fri, Oct 02, 2020 at 01:40:00PM -0400, Jarod Wilson wrote:

quoted

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 <redacted>
Cc: Veaceslav Falico <redacted>
Cc: Andy Gospodarek <andy@greyhouse.net>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: Thomas Davis <redacted>
Cc: <redacted>
Signed-off-by: Jarod Wilson <redacted>
---
 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.

Hm. Would a simple blurb describing the when the changes were made and
why at the top of bonding.rst be sufficient? And then would the rest
of the doc remain as-is (old master/slave language), or with
terminology conversions?

-- 
Jarod Wilson
jarod@redhat.com