Streamlining the Release Archive?
Hi. A handful of contributors have looked into how we can streamline our website and the release package and there are two ideas which come up with regular periodicity: 1. Remove the unified documentation build 2. Split the Boost release into two archives: sources, and documentation The unified documentation build has a different layout in the release compared to the other libraries, which creates special cases for tooling. Splitting the Boost release gives an additional option to users who don’t need the documentation locally. Of course, what goes into these two new archives is completely up for discussion. Happy to hear everyone’s thoughts on this. Regards
Vinnie Falco wrote:
Hi. A handful of contributors have looked into how we can streamline our website and the release package and there are two ideas which come up with regular periodicity:
1. Remove the unified documentation build 2. Split the Boost release into two archives: sources, and documentation
The unified documentation build has a different layout in the release compared to the other libraries, which creates special cases for tooling. Splitting the Boost release gives an additional option to users who don’t need the documentation locally. Of course, what goes into these two new archives is completely up for discussion.
We already provide source-sans-docs release archives here: https://github.com/boostorg/boost/releases Since these are prepared by a CI job I made, and not by release managers, they are "unofficial" but still useful (e.g. for CI).
On Mon, Sep 29, 2025 at 12:31 PM Peter Dimov via Boost < boost@lists.boost.org> wrote:
Vinnie Falco wrote:
Hi. A handful of contributors have looked into how we can streamline our website and the release package and there are two ideas which come up with regular periodicity:
1. Remove the unified documentation build 2. Split the Boost release into two archives: sources, and documentation
The unified documentation build has a different layout in the release compared to the other libraries, which creates special cases for tooling. Splitting the Boost release gives an additional option to users who don’t need the documentation locally. Of course, what goes into these two new archives is completely up for discussion.
We already provide source-sans-docs release archives here:
https://github.com/boostorg/boost/releases
Since these are prepared by a CI job I made, and not by release managers, they are "unofficial" but still useful (e.g. for CI).
Interesting, didn't know they existed. Why the need for separate b2 vs cmake archives? -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supongas Nada -- Robot Dreams - http://robot-dreams.net
René Ferdinand Rivera Morell wrote:
On Mon, Sep 29, 2025 at 12:31 PM Peter Dimov via Boost < boost@lists.boost.org> wrote:
Vinnie Falco wrote:
Hi. A handful of contributors have looked into how we can streamline our website and the release package and there are two ideas which come up with regular periodicity:
1. Remove the unified documentation build 2. Split the Boost release into two archives: sources, and documentation
The unified documentation build has a different layout in the release compared to the other libraries, which creates special cases for tooling. Splitting the Boost release gives an additional option to users who don’t need the documentation locally. Of course, what goes into these two new archives is completely up for discussion.
We already provide source-sans-docs release archives here:
https://github.com/boostorg/boost/releases
Since these are prepared by a CI job I made, and not by release managers, they are "unofficial" but still useful (e.g. for CI).
Interesting, didn't know they existed. Why the need for separate b2 vs cmake archives?
The b2-nodocs archives move the headers into boost/ like the official releases do.
These are two completely separate topics. 1. Remove the unified documentation build. In a boost archive there is a /doc/ folder at the root. This doesn't follow the standard in-libs doc builds format, and so it's not modular, or consistent. It will require many PRs, editing Jamfiles, to move those into each respective libs/. This ought to be done. (But requires effort by each maintainer). PRs are welcome. 2. Split the Boost release into two archives The contents of those two would be... "source only" (for faster downloads) and "full" (including docs. and, keeping backwards compatibility). If there is any question, it is "which of those takes the place of the current download archives". If "full" remains in-place, as the main URL, it will be fully backwards compatible, and not break anything, while offering an alternative "source-only" to speed up downloads. How high priority is that (for end-users, or for boost). Yes, it's on the radar (as a project), but there are always many other tasks at any moment. Or use https://github.com/boostorg/boost/releases
On Mon, Sep 29, 2025 at 12:43 PM Sam Darwin via Boost <boost@lists.boost.org> wrote:
These are two completely separate topics.
1. Remove the unified documentation build.
In a boost archive there is a /doc/ folder at the root. This doesn't follow the standard in-libs doc builds format, and so it's not modular, or consistent. It will require many PRs, editing Jamfiles, to move those into each respective libs/. This ought to be done. (But requires effort by each maintainer). PRs are welcome.
Not really. The root /doc/ tree build aliases the doc targets that are already in the libraries it builds. So the changes are very minimal (as was the design intent when I created all those doc build targets). Yes, there is a need for PRs. But most of those will be to update the top level redirect html file to point to local docs. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supongas Nada -- Robot Dreams - http://robot-dreams.net
On Mon, Sep 29, 2025 at 10:42 AM Sam Darwin <samuel.d.darwin@gmail.com> wrote:
...It will require many PRs, editing Jamfiles, to move those into each respective libs/. This ought to be done. (But requires effort by each maintainer).
We should probably pick one candidate library for refactoring, and then just do it and see what happens. Any preferences for any particular library? Thanks
El 29/09/2025 a las 19:18, Vinnie Falco via Boost escribió:
Hi. A handful of contributors have looked into how we can streamline our website and the release package and there are two ideas which come up with regular periodicity:
1. Remove the unified documentation build 2. Split the Boost release into two archives: sources, and documentation
The unified documentation build has a different layout in the release compared to the other libraries, which creates special cases for tooling. Splitting the Boost release gives an additional option to users who don’t need the documentation locally. Of course, what goes into these two new archives is completely up for discussion.
Happy to hear everyone’s thoughts on this.
What about the HTML documentation files distributed with some libraries (e.g. Serialization)? Should we erase them for the source archives? Best, Ion
Ion Gaztañaga wrote:
El 29/09/2025 a las 19:18, Vinnie Falco via Boost escribió:
Hi. A handful of contributors have looked into how we can streamline our website and the release package and there are two ideas which come up with regular periodicity:
1. Remove the unified documentation build 2. Split the Boost release into two archives: sources, and documentation
The unified documentation build has a different layout in the release compared to the other libraries, which creates special cases for tooling. Splitting the Boost release gives an additional option to users who don’t need the documentation locally. Of course, what goes into these two new archives is completely up for discussion.
Happy to hear everyone’s thoughts on this.
What about the HTML documentation files distributed with some libraries (e.g. Serialization)? Should we erase them for the source archives?
If you look here https://github.com/boostorg/boost/releases you'll see that the size of the b2-nodocs archive is about half that of the corresponding cmake one. That's because the doc/ subdirectories are deleted from the nodocs archive. https://github.com/boostorg/boost/blob/0bdff1d86f4e9482c698c75edb222c6d9d3d9...
participants (5)
-
Ion Gaztañaga -
Peter Dimov -
René Ferdinand Rivera Morell -
Sam Darwin -
Vinnie Falco