Re: Do Tools Need Formal Reviews?

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2024-10-09 11:18:05

On 10/9/24 01:39, Vinnie Falco via Boost wrote:
> 
> Tools are not user-facing (where "user" is defined as a Boost user and not
> an author or maintainer).

This is not accurate. Tools are user-facing, although probably to a
lesser degree than libraries. For example, users do need to interact
with b2 to build Boost. Some users (most notably, downstream packagers)
do need to at least install and configure various documentation tools to
build the docs. In some cases, downstream packagers also have to edit
docs or the resulting html output as they package Boost. One example is
to ensure the built docs don't breach privacy and are confined to the
viewer's machine (i.e. remove various web counters and references to
external resources from the generated docs).

In fact, the last part might be a point in favor of holding a review
with an accept/reject decision in the end. If a documentation tool
produces output that relies heavily on external resources that makes
building local documentation prohibitively difficult, that tool should
be rejected. This is just an example in the context of documentation,
but there may be others.

I do not think a simple provision of feedback adequately replaces a
review in this case because the maintainer(s) are free to disregard it
or act at an untimely manner, which means that a Boost release with the
offending tool being used gets shipped and affects users.

Another point is that we should remember that each new external tool is
a dependency of Boost. I think, it is uncontroversial that we should try
to minimize external dependencies, if possible. Regarding internal
tools, we should avoid duplication as this is maintenance cost.
Therefore Boost libraries in general should strive to using common
existing tools rather than add their own solutions. Sure, different
maintainers prefer different tools, and libraries may have different
requirements. However, I think a maintainer should first look though the
existing tool to see if they fit their needs before inventing a new
solution. For this, (a) the existing tools should be known among the
community and (b) there should be a barrier to adding new tools. I think
a review provides both visibility and a barrier.