# PSA: Documenter.jl breaking changes & version capping

**URL:** <https://discourse.julialang.org/t/psa-documenter-jl-breaking-changes-version-capping/16431>\
**Category:** Tooling\
**Tags:** package, documentation, documenter, travis\
**Created:** [October 17, 2018, 7:57am UTC](https://discourse.julialang.org/t/psa-documenter-jl-breaking-changes-version-capping/16431 "2018-10-17T07:57:24Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [October 17, 2018, 7:57am UTC](https://discourse.julialang.org/t/psa-documenter-jl-breaking-changes-version-capping/16431/1 "2018-10-17T07:57:24Z")

</div>

_This is relevant for package developers using [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) for their package documentation._

The upcoming Documenter 0.20 will introduce breaking changes to the way `makedocs` and `deploydocs` arguments are interpreted. This means that most existing `make.jl` scripts have to be updated before they work correctly with the new version.

As you might have already noticed, a bunch of METADATA-registered packages just got hit with automated PRs that cap the Documenter version used in Travis to 0.19. However, it was only possible to do this automatically for about half the packages that use Documenter.

So for packages that did not get a PR (including all unregistered and private ones), you need to cap Documenter manually:

- If you are using a `docs/Project.toml` file (see [the previous PSA on Documenter and projects](https://discourse.julialang.org/t/psa-use-a-project-for-building-your-docs/14974); this is the recommended setup), you should make sure that you have a `[compat]` section in there, capping Documenter to 0.19:

- If you are installing Documenter in `.travis.yml` directly (on Julia 0.7/1.0), you should update the line with the `Pkg.add` to be something like:

- 🦕 If you are building docs on Julia \<= 0.6, you do not need to worry, as Documenter 0.20 will be 0.7/1.0-only. But if upgrading the package is on the roadmap, you could change to `Pkg.add("Documenter")` in `.travis.yml` to `Pkg.add("Documenter", v"0.19", v"0.20-")` as a reminder.

In the future, we would like to reserve the right to make breaking changes to Documenter in accordance with semver. This means that you should either have Documenter fixed to a specific 0.x version or be ready to deal with potential sudden documentation build failures when new Documenter versions get released.

There will also be another announcement on Discourse when 0.20 gets tagged and merged. It will also include a guide for upgrading your `make.jl` file. But for those who are curious, you may take a look at the [current CHANGELOG](https://github.com/JuliaDocs/Documenter.jl/blob/master/CHANGELOG.md) to get a glimpse of the upcoming changes.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [October 17, 2018, 8:06am UTC](https://discourse.julialang.org/t/psa-documenter-jl-breaking-changes-version-capping/16431/2 "2018-10-17T08:06:09Z")

</div>

I would like to thank the Documenter.jl maintainers for providing all this support for the API change in addition to making such a useful package. This kind of approach is exemplary for an open source package.

---

<div class="post-metadata">

**Author:** ![cpfiffer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cpfiffer/32/208747_2.png) [@cpfiffer](https://discourse.julialang.org/u/cpfiffer)\
**Post date:** [October 17, 2018, 12:28pm UTC](https://discourse.julialang.org/t/psa-documenter-jl-breaking-changes-version-capping/16431/3 "2018-10-17T12:28:01Z")

</div>

This was very well handled! Thank you.

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [October 25, 2018, 7:03am UTC](https://discourse.julialang.org/t/psa-documenter-jl-breaking-changes-version-capping/16431/4 "2018-10-25T07:03:36Z")

</div>

Bumping this to the top just one more time. We intend to tag Documenter 0.20 over the weekend.

If you haven’t capped Documenter’s version yet, be warned that your automatic documentation deployments will most likely start **breaking silently next week**. As far as I can tell, many of the repositories that did not get an automated PR will be affected.

At this point, the best option is probably to update `make.jl` as soon as 0.20 gets released and cap Documenter to that version. It involves only a few small changes to the `makedocs` and `deploydocs` arguments.