Show warning when an old ex_doc version is used.

[jannikbecher]

Woytek asked me to open the PR here :)
He already mentioned that it's probably not a good idea to add hex_core as additional dependency

[jannikbecher]

just borrowed this from the hex repo. Probably no the correct options for this use case

[josevalim]

Can we use the Hex API directly instead? 🤔

[jannikbecher]

While testing this I figured this is a classical chicken-egg-problem :-D
Isn't it a better solution to just advice the package maintainer to use {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}?

[wojtekmach]

WDYM about the chicken and egg problem exactly?

it doesn’t matter if people have >=0.0.0 or ~>0.30 as both would resolve to the same latest version.

Hex API is private but yeah we can use it and if it breaks we can solve it in ExDoc. We should only check version when running mix docs though, and not when ExDoc is an escript, because only then we have reliable access to Hex.

[jannikbecher]

WDYM about the chicken and egg problem exactly?

That you will only get the warning, when you already have installed the lastest ExDoc version.

Hex API is private but yeah we can use it and if it breaks we can solve it in ExDoc. We should only check version when running mix docs though, and not when ExDoc is an escript, because only then we have reliable access to Hex.

Feels a bit complicated to maintain this. Isn't it better to check the deps if it uses the latest version and just warn based on that information?

[garazdawi]

I'm not sure I like the idea of a documentation tool making a connection to the internet by default. I assume that some (many?) will run their build behind a firewall and at least the one I'm behind logs attempts to get out. So not matter what, I think it would be good idea to put this behind a configuration option.

[wojtekmach]

@jannikbecher got it re checkin & egg problem. Not a big deal, can be said about many things.

Isn't it better to check the deps if it uses the latest version and just warn based on that information?

Is it? I might be misunderstanding the problem statement but I don't see how that solves anything. As I mentioned in the example, >=0.0.0 and ~>0.30 will resolve to the same latest version (until 1.0 but we'll worry about that later) so why would we only warn on the latter?

@garazdawi good call.

Something that wasn't mention was Hex already has a task to check for deps:

Maybe we nudge people to use mix hex.outdated instead and they naturally opt-in into this instead of bolting this onto ExDoc?

[jannikbecher]

Is it? I might be misunderstanding the problem statement but I don't see how that solves anything. As I mentioned in the example, >=0.0.0 and ~>0.30 will resolve to the same latest version (until 1.0 but we'll worry about that later) so why would we only warn on the latter?

The problem is some maintainers pin the ExDoc version to a specific minor version like this "~> 0.29.3"

[wojtekmach]

One idea is:

aliases: [
  "hex.publish": ["hex.outdated ex_doc", "hex.publish"]
]

and then:

$ mix hex.publish
There is newer version of the dependency available 0.31.1 > 0.30.9!

Source   Requirement  Up-to-date
mix.exs  ~> 0.20      Yes

Up-to-date indicates if the requirement matches the latest version.
Building ecto 3.11.1
(...)

this currently does not work because Mix continues executing hex.publish. We can solve it by using Mix.raise in hex.outdated, perhaps via opt-in flag.

[wojtekmach]

speaking of CI, the easiest way to solve this problem is exactly there. Here's an excerpt from my usual checks. Just a one line change:

  - run: mix deps.get --check-locked

  - run: mix format --check-formatted
    if: ${{ matrix.lint }}

  - run: mix deps.unlock --check-unused
    if: ${{ matrix.lint }}

  - run: mix deps.compile

  - run: mix compile --warnings-as-errors
    if: ${{ matrix.lint }}

  - run: mix test
    if: ${{ ! matrix.lint }}

  - run: mix test --warnings-as-errors
    if: ${{ matrix.lint }}

+ - run: mix hex.outdated ex_doc

[josevalim]

What if we call Mix.Task.run("hex.outdated", ["ex_doc"]) by default on mix docs and handle the case the task is not available? The only changes we'd need to make are:

1. Replace the word "dependency" by the actual dependency
2. Add an option to not log anything if it is up to date?

[wojtekmach]

Similar to @garazdawi comment, if we are on a train or flight we won't be able to generate docs on bad connectivity. But I suppose there's an incentive for community as a whole to be on the latest version because there's consistent experience all around.

Should we at least add an option to opt-out?

Your Hex changes sound like good ideas regardless. :)

[josevalim]

@wojtekmach the registry is frequently updated locally anyway, right? We could call hex.outdated with HEX_OFFLINE set, for example, no?

[wojtekmach]

@josevalim yes, good call.

Another way to solve this problem is to use external tools like Dependabot. I don't personally use it but I could be convinced to use it just for ExDoc. Here's an untested dependabot.yml that should work (adapted from https://github.com/philss/floki/blob/main/.github/dependabot.yml)

version: 2
updates:
- package-ecosystem: mix
  directory: "/"
  schedule:
    interval: daily
    time: "08:00"
  allow:
    - dependency-name: ex_doc

I believe the benefit would be it's even easier for maintainers, they just merge a PR that is automatically created soon after there's a new ExDoc version.