Traditionally, tools used by authors and maintainers are quietly integrated with oversight from owners and release managers. Examples include saxon-he and docca (https://github.com/boostorg/docca). Recently there have been noises made expressing the desire for the formal review process to be applied to tools as well. The purpose of this post is to explain why this is a bad idea. There are two kinds of tools. External tools, brought into use by the project through the scripts which create the release, and internal tools which are in repositories added to the superproject. An example of an external tool is asciidoctor: https://asciidoctor.org/ This was quietly added and the command line tool is required to be installed in order to build a Boost release, as libraries such as Boost.mp11 or Boost.Unordered need it for producing their documentation. The Asciidoctor author provides the installation package and provides all support. The only documentation requirement for Boost libraries is that they render into HTML and that "b2 doc" works. A formal review to adopt "asciidoctor" as an available external tool could result in REJECT. This serves no useful purpose other than to make things more difficult for the author or maintainer. They can still use asciidoctor but would have to do it locally and commit the resulting HTML output to the repository, as the tool would not be available to the release process. This is objectively worse for everyone. An example of an internal tool is BoostLook: https://github.com/boostorg/boostlook This is a set of CSS files and Ruby scripts used by some libraries to style their Asciidoctor documentation. This was quietly added to the superproject as the release will need it for some of the libraries to build. Discussion with owners happened beforehand; the files for this tool were originally in the website-v2-docs repo (https://github.com/boostorg/website-v2-docs) but the objection was made (rightly so) that the website-v2-docs repo was too large to add to the superproject. Thus the files were put into their own small repository. A formal review to adopt BoostLook as an internal tool could result in a REJECT outcome. This serves no useful purpose other than to make things more difficult for maintainers. They would manually inline the boostlook files in their repository and be responsible for keeping it up to date (submodules in libraries are intentionally not cloned by the release script). Tools are not user-facing (where "user" is defined as a Boost user and not an author or maintainer). I've seen a lot of intellectual gymnastics trying to justify why tools are the equal of libraries but they fail in light of an obvious fact: tools no longer in use can be removed from the superproject without a tsunami of mailing list protest. It is true that tools which Boost end-users find useful can be adopted, but they do not come with the same promise of forever support the way that libraries do. They are only supported to the extent to which the Boost libraries need them. My maybe-unpopular opinion: b2 was correct to move to an independent repository, as this can come with implied lifetime support. There's a recurring theme: tools are not libraries, despite Robert Ramey's sincere efforts to formally review them as such. A tool is an administrative construct designed to facilitate the efforts of authors and maintainers when they wish to make use of the tool in more than one library. The use of the tool is still possible in a Boost library, without the tool becoming part of the superproject, yet with more effort and opportunity for mistakes. It is for this reason that we do not use the formal review process for tools, as rejecting a tool has only disadvantages for existing libraries. The very last thing we need to do now is to make things harder for authors and maintainers. An argument used to justify a formal review is that the resulting feedback can improve the tool. I agree that feedback is generally helpful, this is true even if there is no formal review. That is, there is no requirement for a formal review to be ongoing for someone to provide feedback. Just provide the feedback. Tools are boring, and unlikely to attract a significant number of review responses. Formal reviews of proposed internal tools which receive a very small number of reviewers do not signal strong consensus and I believe harm morale. The informal process used for oversight on the internal and external tools Boost uses to produce its releases has worked well, and no convincing rationale has been put forth for why it should change. We should not invoke the formal review process for tools. Thanks
Le mardi 08 octobre 2024 à 15:39 -0700, Vinnie Falco via Boost a écrit :
An argument used to justify a formal review is that the resulting feedback can improve the tool. I agree that feedback is generally helpful, this is true even if there is no formal review. That is, there is no requirement for a formal review to be ongoing for someone to provide feedback. Just provide the feedback. Tools are boring, and unlikely to attract a significant number of review responses. Formal reviews of proposed internal tools which receive a very small number of reviewers do not signal strong consensus and I believe harm morale.
I would like to emphasize this argument, and adds another one in favor of a review. Reviews give visibility to the tool, it will result in increased available information about what the tool do, how to use it, and ideally result in the establishment on some guidelines on how to use the tool for boost. It will makes maintainers aware that there's a new tool available, and it may bring value to your library. Going back to the specifics of Dmitry's pretty printer testing, i think there's great value in reviewing that, because it's a quite new thing, and it's more than just a tool because pretty printers have bugs that will directly impact the customer experience. I don't see how the outcome could be reject, but i do think that more feedback / other opinions on this would be welcomed. And i do hope more libraries will think about including pretty printers and test them. Regards, Julien
On Tue, Oct 8, 2024 at 10:56 PM Julien Blanc
...more feedback / other opinions on this would be welcomed.
I agree. Why is a formal review needed for this? Just give your feedback and opinions now, without waiting for a review manager. I think the author will appreciate it! Thanks
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.
On 10/8/24 3:39 PM, Vinnie Falco via Boost wrote:
Traditionally, tools used by authors and maintainers are quietly integrated with oversight from owners and release managers. Examples include saxon-he and docca (https://github.com/boostorg/docca). Recently there have been noises made expressing the desire for the formal review process to be applied to tools as well. The purpose of this post is to explain why this is a bad idea.
I don't think it's a good idea in general for authors to have carte blanche to add whatever tools they want to Boost because it _does_ affect others in the project. Complicating the Boost development toolchain without approval seems to fly in the spirit of fraternity that underpins Boost. I was also under the impression that Dmitry's tool would be user-facing. We've had nothing but popular reception about more debugger support and I think users would be interested in anything that helps them abstract this. - Christian
On Wed, Oct 9, 2024 at 8:33 AM Christian Mazakas via Boost < boost@lists.boost.org> wrote:
I don't think it's a good idea in general for authors to have carte blanche to add whatever tools they want to Boost because it _does_ affect others in the project.
Well, yes that is correct. The custom is for the author to approach one of Boost's senior citizens to integrate it safely into the superproject and this also serves as a checkpoint for oversight. This doesn't need to rise to the level of a formal review, however. Thanks
No dia 9 de out. de 2024, às 00:40, Vinnie Falco via Boost
escreveu: […]
We should not invoke the formal review process for tools.
I think reviews are useful to improve the quality of submissions, so it is only natural that they can be applied to tools as well going forward. For this tool in particular, its potential usage goes beyond an internal utility for Boost authors, which makes it more sensible that it be reviewed publicly. Either way, the author has explicitly requested the review, which to me should settle all arguments about whether that review should take place or not. Joaquin M Lopez Munoz
On Wed, Oct 9, 2024 at 10:31 AM Joaquín M López Muñoz via Boost < boost@lists.boost.org> wrote:
I think reviews are useful to improve the quality of submissions, so it is only natural that they can be applied to tools as well going forward. For this tool in particular, its potential usage goes beyond an internal utility for Boost authors, which makes it more sensible that it be reviewed publicly. Either way, the author has explicitly requested the review, which to me should settle all arguments about whether that review should take place or not.
1. Tools are not "submissions" 2. Formal reviews are to determine whether a library should be accepted. 3. I don't see any tools listed here: https://www.boost.org/doc/libs/ 4. I don't see any tools listed here: https://www.boost.io/libraries/mini/ 5. A review should take place, no one is stopping you. 6. A formal review should not take place. Tools are not libraries. I'll be curious to see how this plays out since review wizards have informed me they only get involved for library submissions. Thanks
On Wed, Oct 9, 2024 at 7:38 PM Vinnie Falco via Boost
3. I don't see any tools listed here: https://www.boost.org/doc/libs/
Minor point.. Tools are listed at the bottom of the right menu here: https://www.boost.org/doc/ -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
1. Tools are not "submissions" 2. Formal reviews are to determine whether a library should be accepted. 3. I don't see any tools listed here: https://www.boost.org/doc/libs/ 4. I don't see any tools listed here: https://www.boost.io/libraries/mini/ 5. A review should take place, no one is stopping you. 6. A formal review should not take place. Tools are not libraries.
I'll be curious to see how this plays out since review wizards have informed me they only get involved for library submissions.
Thanks
I don't see any governance referendums listed their either yet we made it happen. There's a clear consensus that the formal review process should be applied to tools. If the sole argument against a review is "This is how we've always done it" then that's just a failure to adapt to the current environment. Matt
El 10/10/2024 a las 2:37, Vinnie Falco escribió:
On Wed, Oct 9, 2024 at 10:31 AM Joaquín M López Muñoz via Boost
wrote: I think reviews are useful to improve the quality of submissions, so it is only natural that they can be applied to tools as well going forward. For this tool in particular, its potential usage goes beyond an internal utility for Boost authors, which makes it more sensible that it be reviewed publicly. Either way, the author has explicitly requested the review, which to me should settle all arguments about whether that review should take place or not.
[...] 3. I don't see any tools listed here: https://www.boost.org/doc/libs/ 4. I don't see any tools listed here: https://www.boost.io/libraries/mini/
Their place is https://www.boost.org/doc/libs/release/tools https://www.boost.io/doc/libs/release/tools Joaquin M Lopez Munoz
My 2 cents... 1. If there are going to be Boost developed tools, they should be a review for them. And everyone else has mentioned the reasons I would have mentioned. So not going to say more on that. 2. I generally don't think Boost should develop tools. My reason is simple.. It's best to focus on what Boost does well. And to present a single front to users. It's one of the reasons why I moved B2 development out of Boost. I realize this is somewhat contradictory to my stated support for a review of the debug printer tool. But (1) does have a big if on it. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net
participants (8)
-
Andrey Semashev
-
Christian Mazakas
-
Joaquin M López Muñoz
-
Joaquín M López Muñoz
-
Julien Blanc
-
Matt Borland
-
René Ferdinand Rivera Morell
-
Vinnie Falco