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

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

[Li Wang via ltp]

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/``).
+
+  - 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/``).
+
+  - 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).
+  - New code should not depend on ``tso_`` unless strictly necessary.
+
+**Notes:**
+
+- 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.
+
 Shell API
 ---------
 
-- 
2.52.0


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

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

[Petr Vorel]

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

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

[Andrea Cervesato via ltp]

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


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

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

[Li Wang via ltp]

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

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