Re: [LTP] [PATCH] doc/developers: document tst_/tse_/tso_ library namespaces

[Petr Vorel <pvorel@suse.cz>]

Hi Li,

> This helps contributors choose the correct layer when adding new library
> code and clarifies expectations around legacy components.

> Follow-up: eef750db28 ("libs: adopt tse_ prefix for extended (non-core) library")
> Follow-up: 751df4fa64 ("include/old: rename legacy headers to tso_* namespace")
> Signed-off-by: Li Wang <liwang@redhat.com>
> ---
>  doc/developers/ltp_library.rst | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)

> diff --git a/doc/developers/ltp_library.rst b/doc/developers/ltp_library.rst
> index f76cbb75e..bb2677622 100644
> --- a/doc/developers/ltp_library.rst
> +++ b/doc/developers/ltp_library.rst
> @@ -15,6 +15,34 @@ for :doc:`writing tests <../developers/writing_tests>`
>  #. Do not add new API functions to the old API. Add new functions to
>     ``tst_.[ch]`` files.

> +Library naming and scope
> +------------------------
> +
> +To keep the library API easy to navigate and to make layering explicit, LTP
> +library components follow these naming rules:
> +
> +- **tst_**: Core LTP library API (located in ``lib/``).
nit: maybe also use :master: for lib/ to make it clickable?
> +
> +  - Stable, widely used interfaces intended for general consumption by tests.
> +  - New public APIs should normally live here (in ``tst_*.h`` / ``tst_*.c``).
> +
> +- **tse_**: Non-core / extended library code (located in ``libs/``).
nit: and here as well?

> +
> +  - Optional or specialized helpers that are not part of the core API.
> +  - May have narrower scope or fewer stability guarantees than ``tst_``.
> +  - Can be promoted to ``tst_`` later if it becomes broadly useful and stable.
> +
> +- **tso_**: Legacy / old library code.
> +
> +  - Kept for backward compatibility.
> +  - No new features should be added; only minimal fixes are acceptable (e.g. build fixes, correctness fixes, security fixes).
very nit: maybe split long line?

> +  - New code should not depend on ``tso_`` unless strictly necessary.
> +
> +**Notes:**

nit: I'd prefer the standard note (can be changed before merge):

.. note::

> +
> +- Prefer adding new code to ``tst_`` or ``tse_``; avoid introducing new ``tso_`` components.
> +- When adding a new public interface, document where it belongs (``tst_`` vs ``tse_``) and why.

LGTM, but I'd prefer more developers acked it.

Reviewed-by: Petr Vorel <pvorel@suse.cz>

Kind regards,
Petr

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp