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

[Li Wang]

Hi Andrea, Petr,

Patch merged (with Petr's suggestions), thanks!

On Wed, Feb 18, 2026 at 9:41 PM Andrea Cervesato <andrea.cervesato@suse.com>
wrote:

> 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
>
>

-- 
Regards,
Li Wang