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

[Andrea Cervesato]

Hi!

On Mon Feb 2, 2026 at 11:14 AM CET, Petr Vorel wrote:
> 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

With Petr suggestions,

Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com>


-- 
Andrea Cervesato
SUSE QE Automation Engineer Linux
andrea.cervesato@suse.com