RFC: Requiring Documenter.jl minor version to be fixed

Specific Domains
, ,
1

This is addressed to package developers using Documenter.jl to build their docs. I would like to gather some feedback on whether fixing the minor version of Documenter should be the recommended practice for Documenter deployments.

There’s a corresponding issue #460 open on Documenter’s issue tracker, so it would probably be best to have the actual discussion there to avoid fragmenting it. Posting here to reach a wider audience.

I’ll just copy the contents of the issue’s OP:

Currently Documenter deployments usually just have

after_success:
  - julia -e 'Pkg.add("Documenter")'
  - julia -e 'cd(Pkg.dir("PACKAGE_NAME")); include(joinpath("docs", "make.jl"))'

in their .travis.yml file (recommended by the docs). Therefore on every Travis run the latest Documenter available in METADATA gets installed.

This means that currently it is impossible to make breaking changes to Documenter without breaking existing deployments. This came up recently when the old authentication methods were removed – we ended up with quite a lot of documentation builds failing. A likely near-future breaking change would be switching to having the native HTML output be the default. The issue is further compounded by the fact that it’s basically impossible to notice any deprecation warnings or doc build failures on Travis.

We could therefore strongly recommend that people fix the minor version of Documenter in their deployments. Sure, they would have to keep an eye on Documenter’s releases and update manually, but it would be better than broken builds.

We could achieve this by recommending using Pkg.add("Documenter", v"x.y", v"x.(y+1)-") in .travis.yml, so that the deployments would only receive patch-level updates automatically.

It might be worth going one step further – Documenter could enforce this, unless the user explicitly requests that automatically updating minor and major versions is what they want. One potential way would be to have a Documenter.versioncheck(v"x.y") API, which we would guarantee to remain constant even through major versions. Documenter would then refuse to run unless the installed version matches. Alternatively, if we could somehow have custom docs/REQUIRE files, then Documenter could check that to see if Documenter is fixed to a specific minor version.

PS: not actually sure what the correct category for this type of post would be.

3 Likes
2

Shouldn’t breaking changes be a major release?

3

That’s true, but then the question is whether the major version should be fixed or not. At the moment Documenter.jl is doing 0.x releases, so breaking changes would be in minor releases though, hence the way I phrased it.

4

I think that’s up to users. You should expect that, if you are not setting version bounds, you can have breakage. And “breakage” with docs isn’t really bad at all: it doesn’t affect users. I believe it flips your CI badge red too, alerting you that there’s something wrong? If not, that’s the only change I think would be necessary.

I’d say go ahead with improving Documenter.jl without worry.

5

It won’t flip the CI badge (if set up as above). The builds happen in the after_success section, and any failures here go completely unreported. Building the docs as part of the tests would allow working around that, in principle.