Release Notes: Markdown to replace QBK
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? -- Regards, Vinnie Follow me on GitHub: https://github.com/vinniefalco
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).
On Fri, Feb 17, 2023 at 11:40 AM Peter Dimov via Boost <boost@lists.boost.org> 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
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 <boost@lists.boost.org> 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.
On Fri, Feb 17, 2023 at 1:52 PM Peter Dimov via Boost <boost@lists.boost.org> 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 <boost@lists.boost.org> 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 11:56 AM René Ferdinand Rivera Morell <grafikrobot@gmail.com> 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. Thanks
On Fri, Feb 17, 2023 at 2:04 PM Vinnie Falco <vinnie.falco@gmail.com> wrote:
On Fri, Feb 17, 2023 at 11:56 AM René Ferdinand Rivera Morell <grafikrobot@gmail.com> 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 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. If meta/libraries.json could override where to find release_notes.md (including that it might have a different name), that would work better. You may find the list of file names which github treats specially at https://github.com/joelparkerhenderson/github-special-files-and-paths of use when thinking about defaults to use. The obvious is CHANGELOG (which I don't like the name of either, what's wrong with release_notes.md?). Niall
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 Fri, Feb 17, 2023 at 12:24 PM Andrey Semashev via Boost <boost@lists.boost.org> 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.qbk>
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.
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. Thanks
On 2/17/23 23:35, Vinnie Falco wrote:
On Fri, Feb 17, 2023 at 12:24 PM Andrey Semashev via Boost <boost@lists.boost.org> 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.qbk>
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.
Andrey Semashev wrote:
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.
I mostly copy-paste the Asciidoc release notes into the PR, the formats are close enough. Quickbook is kind of obsolete at this point, and markdown-like formats have won. It might be a better markup language, but this doesn't really matter. (There's a reason Asciidoc supports markdown-like headings and code blocks, for instance.) The fact that Daniel James is no longer contributing doesn't help; this makes Quickbook unmaintained in addition to obsolete.
On Fri, 17 Feb 2023 at 20:40, Peter Dimov via Boost <boost@lists.boost.org> 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 2/17/23 22:35, Vinnie Falco via Boost 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?
Please no. Markdown is a very limited and poorly documented format. Also, I oppose to having preference to GitHub or any other particular service provider in basic Boost facilities, such as documentation format. Boost should be easy to move between service providers. In particular, it should not require one to convert documentation to a different format.
On Fri, Feb 17, 2023 at 12:14 PM Andrey Semashev via Boost <boost@lists.boost.org> 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 2/17/23 23:22, Vinnie Falco wrote:
On Fri, Feb 17, 2023 at 12:14 PM Andrey Semashev via Boost <boost@lists.boost.org> 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.
I don't have much problem with that as long as it works. And it does work, and does a much better job than Markdown.
If you think Markdown is unpopular (it isn't) you should see how many projects outside of Boost use Quickbook.
I'm not saying anything about its popularity, it's the last thing that I'm interested in, actually. Markdown is good for some things. Like writing a small simple document, like a readme. But not good enough for library documentation.
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.
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.
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.
It is tied in regards that only GitHub truly knows how to render GitHub Markdown. I tried different tools to convert GitHub Markdown to HTML, some claimed they supported the GitHub flavor, and it wasn't perfect. Though that was a few years ago, and I didn't bother trying since.
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.
Choosing a service-independent well-documented format for documentation has no added costs. Especially, when such format is already used. I consider the ability to easily switch service providers an important disaster resilience feature (where "disaster" has a broad meaning).
On Fri, Feb 17, 2023 at 12:42 PM Andrey Semashev via Boost <boost@lists.boost.org> 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
On Fri, Feb 17, 2023 at 12:42 PM Andrey Semashev via Boost <boost@lists.boost.org> 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. Thanks
Vinnie Falco wrote:
On Fri, Feb 17, 2023 at 12:42 PM Andrey Semashev via Boost <boost@lists.boost.org> 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 Fri, Feb 17, 2023 at 1:22 PM Peter Dimov via Boost <boost@lists.boost.org> wrote:
I'm not sure why this maters in this case.
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). Thanks
On Friday, February 17th, 2023 at 1:37 PM, Vinnie Falco via Boost <boost@lists.boost.org> 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
On Saturday, February 18th, 2023 at 1:59 AM, Ahmed Charles <me+boost@ahmedcharles.com> wrote:
On Friday, February 17th, 2023 at 1:37 PM, Vinnie Falco via Boost boost@lists.boost.org 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.
I forgot to add the relevant links: https://github.github.com/gfm/ https://spec.commonmark.org/ -- Ahmed Charles
participants (7)
-
Ahmed Charles -
Andrey Semashev -
Mateusz Loskot -
Niall Douglas -
Peter Dimov -
René Ferdinand Rivera Morell -
Vinnie Falco