Document stability guarantees

[matklad]

Looks like NixOS, the distro I use, is going to package asciidoctor-web-pdf: NixOS/nixpkgs#142727

Which makes me ask a question: for my slides, can I rely on system's asciidoctor-web-pdf (which might receive updates), or should I pin a specific version for each talk I made? For slides, which I make once, and then don't touch for years, it is pretty important that stuff continues to work without my active intervention. So I have couple of asks here:

• Document expectations about stability in the Readme. Can I expect future versions of asciidoctor to produce the same output as existing ones? If not, what's the expected pace of newer versions?
• Consider committing to super-strict compatibility guarantees. For document-processing systems, I think there's a lot of value in strong backwards-compatibility story. Not sure if that's feasible for asciidoctor-web-pdf: JS ecosystem is shifting sands, chromium is ever upgrading, and we expose programmatic API (via --template-require). But, if that's feasible, that'd be super-cool!

[ggrossetie]

Which makes me ask a question: for my slides, can I rely on system's asciidoctor-web-pdf (which might receive updates), or should I pin a specific version for each talk I made? For slides, which I make once, and then don't touch for years, it is pretty important that stuff continues to work without my active intervention.

I think it's a good practice to note down the version of the generator used to produce something (no matter what the compatibility guarantees are).
Just like when we write code, we will often specify the language/compiler version.

Document expectations about stability in the Readme. Can I expect future versions of asciidoctor to produce the same output as existing ones?

You can read more about Asciidoctor versioning and release policies: https://docs.asciidoctor.org/about/version-and-release-policies/

Under the hood, Asciidoctor Web PDF is using Asciidoctor, so we cannot guarantee more than what Asciidoctor guarantees.
Meaning that, if Asciidoctor release version 3.0.0 we will eventually make the changes to be compatible with this new version and release a new major version.

Asciidoctor Web PDF is using semantic versioning as its versioning system. So if we break backward compatibility (after 1.0.0) it will be a major release (2.0.0).

To answer your question regarding the output, I think it's pretty safe since Asciidoctor gives you complete control over how the output is generated. So even if we decide to remove a built-in converter or make "breaking changes" (in a major version), nothing prevents you from using a previous version of this converter.
So if you want "increased stability", I would recommend to use your own converter, but I think that's already the case no?

If not, what's the expected pace of newer versions?

Can't really tell, Asciidoctor 2.0.0 has been released on the 22th march 2019 and Asciidoctor 3.0.0 is not in sight.

Consider committing to super-strict compatibility guarantees. For document-processing systems, I think there's a lot of value in strong backwards-compatibility story.

There are two sides, AsciiDoc the language and AsciiDoc processors (such as Asciidoctor).
The AsciiDoc Working Group will drive the evolution of the AsciiDoc language but I expect strong compatibility guarantees.
Regarding AsciiDoc processors, it's up to each projects/communities to define what they want to do.
I would say that the Asciidoctor community is "conservative" or at least we carefully weigh the benefits and drawbacks and make sure that it won't have an high impact.

Not sure if that's feasible for asciidoctor-web-pdf: JS ecosystem is shifting sands, chromium is ever upgrading, and we expose programmatic API (via --template-require). But, if that's feasible, that'd be super-cool!

If you want precisely the same output pixel-wise I don't think that's feasible. As you said, newer Chromium version might slightly change how the HTML/CSS is rendered.

To summarize:

• Note down the version of the generator used in your AsciiDoc file
• Expect strong compatibility guarantees from AsciiDoc (the language)
• When upgrading to a major version, expect breaking changes

Please note that this project is still in alpha so we might break things before 1.0.0.