From:   David Vernet <void@manifault.com>
To:     bpf@vger.kernel.org
Cc:     ast@kernel.org, daniel@iogearbox.net, andrii@kernel.org,
        martin.lau@linux.dev, song@kernel.org, yhs@meta.com,
        john.fastabend@gmail.com, kpsingh@kernel.org, sdf@google.com,
        haoluo@google.com, jolsa@kernel.org, linux-kernel@vger.kernel.org,
        kernel-team@meta.com, toke@redhat.com, corbet@lwn.net,
        linux-doc@vger.kernel.org, brouer@redhat.com, bagasdotme@gmail.com,
        linux-api@vger.kernel.org
Subject: [PATCH bpf-next v3 0/1] Document kfunc lifecycle / stability expectations
Date:   Fri,  3 Feb 2023 09:57:26 -0600
Message-Id: <20230203155727.793518-1-void@manifault.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

This is v3 of the proposal for documenting BPF kfunc lifecycle and
stability.

v1: https://lore.kernel.org/all/20230202163056.658641-1-void@manifault.com/
v2: https://lore.kernel.org/bpf/20230202223557.744110-1-void@manifault.com/T/

Much of this proposal is based on Toke's writing, and group discussions
at BPF office hours.

Changelog
---------
v2 -> v3:
- Add Co-developed-by tag for Toke, and Reviewed-by tag for Bagas.
- s/period period/period (Donald).
- s/other kfuncs may/usually kfuncs will (Donald).
- Remove verbiage encouraging users to upstream BPF programs (Donald and
  Toke).
- Collapse two paragraphs in KF_DEPRECATED section, and apply Toke's
  suggested wording (Toke).
- s/highly encouraged/encouraged (Toke).
- Use phrasing that is less bad than "more similarly" (Toke).
- s/Said in a different way/In other words (Toke).
- Reword section about out-of-tree BPF program kfunc users being
  relevant to discussions, per Toke's suggested wording (Toke).
- Drop unnecessary extra verbiage in paragraph explicitly stating
  that kfuncs have no hard stability guarantees (Toke).
- Reword second paragraph of 3.1 kfunc deprecation to have cleaner
  language (Toke).
- Drop extraneous qualifier regarding a deprecated kfunc being dropped
  early (Toke).

v1 -> v2:
- Move some of the main points of the arguments around. v1 underscored
  quite strongly that kfuncs don't have _any_ stability guarantees.
  While true, it may scare away users who misinterpret the implications
  of that to mean that things will change wildly and at any time.
  Reframe the general flow of the section to be clear that no stability
  is guaranteed, but front-load the content that clarifies why this
  isn't necessarily something to be afraid of for users (Toke, Daniel,
  and others).
- Add a paragraph explaining that out-of-tree BPF programs that use
  kfuncs are relevant to discussions surrounding whether kfuncs should
  be modified or removed. While the onus is on kfunc users to explicitly
  engage with the upstream community to let them know which kfuncs
  they're using and why they're useful, the added paragraph also makes
  it clear that the BPF community will in turn participate in upstream
  discussions to ensure that such users aren't equated with out-of-tree
  module users, and outright ignored. Also make it clear that our hope
  is that BPF programs will be upstreamed on a more regular basis (Toke,
  Daniel, and others).
- Remove patches that add KF_DEPRECATED flag to <linux/btf.h>. They'll
  remain in the documentation for now, and will be merged at a later
  time when it's actually a useful signal for developers (Alexei and
  Daniel).

David Vernet (1):
  bpf/docs: Document kfunc lifecycle / stability expectations

 Documentation/bpf/kfuncs.rst | 126 +++++++++++++++++++++++++++++++++--
 1 file changed, 121 insertions(+), 5 deletions(-)

-- 
2.39.0