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"))'
.travis.ymlfile (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/REQUIREfiles, 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.