On Fri, Feb 17, 2023 at 11:40 AM Peter Dimov via Boost wrote:

The pull request workflow isn't very elegant. It would be better if, say, every author updates meta/release_notes.md in his repo, and the website automatically compiles these (as it currently does for meta/libraries.json).

Yep that is entirely doable! For now we are aiming to disturb existing workflows as little as possible. When we publish the new website repository you should create this as an issue there and it will get done. Thanks

On Fri, Feb 17, 2023 at 1:52 PM Peter Dimov via Boost wrote:

Vinnie Falco wrote:

...

...

The pull request workflow isn't very elegant. It would be better if, say, every author updates meta/release_notes.md in his repo, and the website automatically compiles these (as it currently does for

On Fri, Feb 17, 2023 at 11:40 AM Peter Dimov via Boost wrote: meta/libraries.json).

Yep that is entirely doable! For now we are aiming to disturb existing workflows as little as possible.

Disturbing some existing workflows (such as this one) would actually be a good thing.

Saying this as the person who partly created this workflow.. +1 Changing to markdown is already disturbing existing workflows. So if we are going to disturb. Lets disturb in a more positive direction and do away with the centralized PRs for this. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net

On Fri, Feb 17, 2023 at 2:04 PM Vinnie Falco wrote:

On Fri, Feb 17, 2023 at 11:56 AM René Ferdinand Rivera Morell wrote:

...

Changing to markdown is already disturbing existing workflows. So if we are going to disturb. Lets disturb in a more positive direction and do away with the centralized PRs for this.

We are definitely going to switch to the "lib/x/meta/release-notes.md" workflow but this requires additional code and testing, so I want to go live first with the existing workflow and then triage the feature request in an open issue. Otherwise it will delay the website further (which, at this point I'm sure people are speculating whether it even exists or not as so much time has passed).

Depending on the timing and how quick things get done we might not even see a new release that uses the pull request workflow. Or maybe just one release until we have the per-repo release notes.

Makes sense. I'd rather see the new web site earlier. If delaying the better workflow in this small part helps to get the website sooner.. Hooray! -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supone Nada -- Robot Dreams - http://robot-dreams.net

On 2/17/23 23:14, Niall Douglas via Boost wrote:

On 17/02/2023 19:40, Peter Dimov via Boost wrote:

...

Vinnie Falco wrote:

...

We need to re-render all of this historical release notes, such as:

https://www.boost.org/users/history/version_1_81_0.html

to be in the style of the new website. This is being taken care of, but it will affect the release process as follows:

* Each author will edit the release notes for their library using markdown instead of Quickbook format, as a pull request against a file here:

https://github.com/boostorg/website/tree/master/feed/history

The syntax will be GitHub flavored markdown, with a few Boost-specific extensions (for example, to link against an issue in a boostorg repo).

Does anyone object or have comments about this?

The pull request workflow isn't very elegant. It would be better if, say, every author updates meta/release_notes.md in his repo, and the website automatically compiles these (as it currently does for meta/libraries.json).

I and undoubtedly others already keep their release notes in a markdown file to please github, but it doesn't live in meta/ nor is it going to.

I certainly don't, and I don't see many (any?) Boost libraries maintaining docs in Markdown. I'm not going to convert any in-library release notes I maintain to Markdown. I currently have to convert HTML to QuickBook for Filesystem, and this isn't fun. I'm not going to do this for every library now. And I sure won't ever convert docs to Markdown either.

On 2/17/23 23:35, Vinnie Falco wrote:

On Fri, Feb 17, 2023 at 12:24 PM Andrey Semashev via Boost wrote:

...

...

It is interesting how after spending years on the list, I discover that certain subjects bring up predictable responses :)

...

I'm not going to convert any in-library release notes I maintain to Markdown.

No one is asking you to. This proposal would have you use markdown instead of Quickbook in the combined release notes which are prepared for each release, such as in this file which will be used for 1.82.0:

https://github.com/boostorg/website/blob/master/feed/history/boost_1_82_0.qb...

...

I currently have to convert HTML to QuickBook for Filesystem, and this isn't fun.

Oh I agree with you 100%

...

I'm not going to do this for every library now.

No one is asking you to. This proposal does not change how you write or produce your library documentation. This proposal does not require changing anything in your repository. Peter's proposal however, does require adding and maintaining a new markdown file in your repo.

If the Boost-wide release notes are written in Markdown, I will have to convert the in-library release notes written in QuickBook (that I gradually write during the development cycle) to Markdown. I don't want that. Currently, I can mostly copy-paste the in-library release notes into Boost release notes, with some minor tweaks to fix links to issues and PRs.

...

And I sure won't ever convert docs to Markdown either.

No one is asking you to. However the chances are good that at some point in the future, Quickbook and Boostbook might no longer work because they receive little to no maintenance. If there are errors when your documentation builds, you might have to fix this toolchain yourself. Furthermore, libraries which use Asciidoc are going to experience a significant upgrade in terms of the appearance and functionality of their rendered documentation. Libraries using Quickbook will not have these upgrades. They will be stuck using the old stylesheets which don't have dark mode, no side table of contents, and do not look well integrated into the website. Whoever wants these improvements would have to go into the Boostbook style sheets and fix them. And so on.

I'm mostly fine with how QuickBook docs look currently, thanks. I have my wishes, but those are not about appearance, like dark mode and such. Side ToC would be nice, but lack of one does not outweigh the drawbacks that Markdown and other tools bring.

On Fri, 17 Feb 2023 at 20:40, Peter Dimov via Boost wrote:

Vinnie Falco wrote:

...

* Each author will edit the release notes for their library using markdown instead of Quickbook format, as a pull request against a file here:

https://github.com/boostorg/website/tree/master/feed/history

The syntax will be GitHub flavored markdown, with a few Boost-specific extensions (for example, to link against an issue in a boostorg repo).

Does anyone object or have comments about this?

The pull request workflow isn't very elegant. It would be better if, say, every author updates meta/release_notes.md in his repo, and the website automatically compiles these (as it currently does for meta/libraries.json).

I second that. For GIL, we maintain notes in RELEASES.md which then for Boost release we copy and reformat them to QuickBook manually. Silly. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On Fri, Feb 17, 2023 at 12:14 PM Andrey Semashev via Boost wrote:

Please no. Markdown is a very limited and poorly documented format.

Well, I have more bad news for you. Quickbook is unmaintained as is its required Boostbook support. If you think Markdown is unpopular (it isn't) you should see how many projects outside of Boost use Quickbook. Long-term I am moving to Asciidoc and focusing my energy on making sure that Boost authors who want to use Asciidoc have an easy time of it, and get great results.

Also, I oppose to having preference to GitHub or any other particular service provider in basic Boost facilities, such as documentation format.

"Github flavored markdown" is not tied to GitHub it just became so insanely popular that it is a widely used dialect. Python's markdown processing tools for example use Github flavored markdown.

Boost should be easy to move between service providers.

Fortunately this proposal doesn't change the ease of movement, but I generally disagree with this statement. Making "Boost easy to move between service providers" has a cost, and that cost is paid by everyone on a continuous basis. Moving to another service provider also has a cost, but it is a singular event with extremely low frequency. Since the majority of our energy is spent on not-moving-to-other-service-provider things, we can afford to make switching service providers expensive as long as we get great value from not worrying about ease of movement. Thanks

On Fri, Feb 17, 2023 at 12:42 PM Andrey Semashev via Boost wrote:

Asciidoc could be a somewhat worthy replacement for QuickBook if it integrated with Doxygen. But it doesn't, so it doesn't work for me. It does miss a few other QuickBook features that I use, like importing annotated C++ code. But, I guess, those are not as vital.

We (The C++ Alliance) are working on getting all those things working so that library authors have the option to switch to Asciidoc if they want to, and not lose functionality.

If the Boost-wide release notes are written in Markdown, I will have to convert the in-library release notes written in QuickBook (that I gradually write during the development cycle) to Markdown. I don't want

Yeah, you have a point here. Thanks

Vinnie Falco wrote:

On Fri, Feb 17, 2023 at 12:42 PM Andrey Semashev via Boost wrote:

...

...

"Github flavored markdown" is not tied to GitHub ... It is tied in regards that only GitHub truly knows how to render GitHub Markdown.

Yes this would be a problem.

I am assuming that this is not the case but if it is we would make adjustments as needed.

I'm not sure why this maters in this case.

On Friday, February 17th, 2023 at 1:37 PM, Vinnie Falco via Boost wrote:

I imagine that we would want to limit ourselves to the subset of GitHub flavored markdown that we can actually render (which might be all of it, or some of it).

Note, GitHub Flavored Markdown is a documented set of extensions to CommonMark, with both being released under CC-BY-SA-4.0. It's not proprietary and it is not the case that only GitHub knows what it is, even if they authored the specification of the list of extensions. It is also specified (making it documented, even if perhaps, poorly). This isn't an endorsement of GFM, just a clarification of what it is and is not. -- Ahmed Charles