GitHub

Documenter & semantic versioning

Documenter, like any good Julia package, follows semantic versioning (SemVer). As such, and as the package is currently in the v1.x era of its lifecycle, any changes in Documenter should not break existing uses of the package that rely on documented behaviors.[1]

However, Documenter is relatively complex, and it can sometimes be unclear what constitutes a breaking change. For example, is changing the CSS classes in the HTML themes allowed? What if the user relied on a CSS class in an @raw html-block? If their HTML is no longer rendered correctly, is that a breaking change? Is completely changing the LaTeX compiler a breaking change? What if it breaks a PDF build somewhere due to some math block using a feature that only works with pdflatex?

This page aims to clarify what is and is not covered by the Documenter SemVer guarantees, both as information for users, and as guidance for developers.

This page is not complete!

If you need to rely on something that is currently an internal API or undocumented behavior, open an issue or a pull request to get it documented! There is a good chance that the behavior is already a de factor SemVer guarantee, or can easily be cleaned up and made public API. The goal is to add and document additional SemVer guarantees over time.

Documenter's API guarantees

The following APIs and behaviors are guaranteed not to change:

  • Standard promises about the Julia APIs (public Documenter functions and their documented arguments). In a nutshell, any make.jl making use of just public, documented parts of the Documenter API should always continue working (i.e. builds should complete). The public APIs include all exported functions and types, but is not limited to that –- see the "Reference" section of the manual for a list of public Julia APIs.

  • All documented Documenter behaviors. E.g. the way Documenter determines remote repository links is documented, or what files and with what structure get generated by the HTML builds. The behavior of undocumented edge cases may change, but only in accordance with what is documented.

Experimental APIs

Note that some APIs may explicitly marked experimental. In that case, you can only rely on them within a minor version. The next minor version release may completely change or remove experimental features and APIs.

When relying on an experimental API (either in a Documenter extension package, or in a documentation build environment), you should fix Documenter to the specific compatible minor version(s) with a "tilde specifier" in the Project.toml file.

What is not covered by SemVer

In principle, anything that is not covered by the previous section is, by definition, not part of the public API and is not guaranteed to keep working the way it is working right now.

However, it is worth mentioning a few things explicitly. In particular, this includes things that are currently not part of the API, but should be added (in some way) in the future, but probably need a careful consideration before we commit to them as public APIs.

  • Any time you hook into Documenter's internals in some way. This includes hooking into the seemingly extensible parts of the internals, such as adding additional build steps, or renderers. The long-term aim here is to create clean plugin APIs, but it is unlikely we'll be able to keep the current internals for that.

  • The HTML, TeX, or file structure of the generated documents (unless explicitly documented). This includes the CSS of the HTML themes, and as such any custom CSS overrides may stop working at any point. However, there are many de facto guarantees here that should get documented over time (e.g. for custom themes).

  • The look and feel of the HTML UI and the generated PDF may change considerably from one minor version to another.

  • Anything explicitly marked experimental is not guaranteed to remain stable (see the note above).

Patch versions are probably okay

If you are relying on some non-SemVer behaviors, features, or internals, it probably fine to expect things not to break within a patch release. In this case, you should add a [compat] entry to your Project.toml files with a tilde specifier fixing Documenter's to a specific minor version, e.g.

Documenter = "~1.X"

where X is the minor version you are developing against.

Alternatively, if this is for package documentation, and your docs/make.jl script is relying on some non-SemVer behavior, you can also check in a docs/Manifest.toml file to fully fix the Documenter version. However, it may still be a good idea to include the version bound in the docs/Project.toml file, just as documentation for maintainers.

  • 1Eventually, of course, Documenter 2.0 may break everything. But we don't expect a breaking release in the very near future.