Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
MIME-Version: 1.0
References: <20201002174001.3012643-6-jarod@redhat.com> <20201002121051.5ca41c1a@hermes.local>
 <CAKfmpSecU63B1eJ5KEyPcCAkXxeqZQdghvUMdn_yGn3+iQWwcQ@mail.gmail.com> <20201002.155535.2066858020292000189.davem@davemloft.net>
In-Reply-To: <20201002.155535.2066858020292000189.davem@davemloft.net>
From:   Jarod Wilson <jarod@redhat.com>
Date:   Sat, 3 Oct 2020 15:44:33 -0400
Message-ID: <CAKfmpSd=mSUEThgD_z58wHkyLtHZcZHcK87t+EzXHU2QSxf2Dg@mail.gmail.com>
Subject: Re: [PATCH net-next v2 5/6] bonding: update Documentation for
 port/bond terminology
To:     David Miller <davem@davemloft.net>
Cc:     Stephen Hemminger <stephen@networkplumber.org>,
        LKML <linux-kernel@vger.kernel.org>,
        Jay Vosburgh <j.vosburgh@gmail.com>,
        Veaceslav Falico <vfalico@gmail.com>,
        Andy Gospodarek <andy@greyhouse.net>,
        Jakub Kicinski <kuba@kernel.org>,
        Thomas Davis <tadavis@lbl.gov>, Netdev <netdev@vger.kernel.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Fri, Oct 2, 2020 at 6:55 PM David Miller <davem@davemloft.net> wrote:
>
> From: Jarod Wilson <jarod@redhat.com>
> Date: Fri, 2 Oct 2020 16:12:49 -0400
>
> > The documentation was updated to point to the new names, but the old
> > ones still exist across the board, there should be no userspace
> > breakage here. (My lnst bonding tests actually fall flat currently
> > if the old names are gone).
>
> The documentation is the reference point for people reading code in
> userspace that manipulates bonding devices.
>
> So people will come across the deprecated names in userland code and
> therefore will try to learn what they do and what they mean.
>
> Which means that the documentation must reference the old names.
>
> You can mark them "(DEPRECATED)" or similar, but you must not remove
> them.

Okay, so it sounds like just a blurb near the top of the file
referencing the changes that have been made in the code might be the
way to go here. Tagging every occurrence of master or slave in the doc
inline as deprecated would get ... noisy.

-- 
Jarod Wilson
jarod@redhat.com