PSA: Do not use private APIs, request a feature instead

Hi everyone,

With the v1.7 release, we have received reports of some dependencies no longer working properly on the new release.

Developers should not expect breaking changes from Elixir on minor and patch releases. We outline our compatibility and deprecations policy in our docs: Compatibility and deprecations — Elixir v1.20.2

This means that, if there is something effectively broken in a new release, it is one of:

We messed up and accidentally introduced a regression, which we have to fix
We fixed a bug that you were accidentally relying on. It is still our bad. We will either have to accept this or find a better way to do a bug fix (for example, introduce a new function and deprecate the old one)
Some project (it could be yours) was using private API

Thanks to everyone, we are able to catch the huge majority of the occurrences of 1 and 2 during the RCs. However, there are still many cases where developers are simply using private Elixir modules and functionality - which may be renamed or completely removed in new Elixir versions. We do not provide any guarantees for private functionality. Needless to say, DO NOT USE PRIVATE APIs.

Using private APIs generate a negative cascade effect in the community because it makes developers unable to update to the latest Elixir version.

How to help

If you are a user of a project and you notice it depends on private functionality, consider reporting a bug or submitting a pull request.

If you are a library author and you are using private APIs, don’t. If Elixir has a functionality that you need but it is private, please open up a feature request to make the desired functionality public.

Also, consider running your CI builds against Elixir master. It is as easy as:

- wget https://repo.hex.pm/builds/elixir/master.zip
- unzip -d elixir master.zip
- export PATH=$(pwd)/elixir/bin:${PATH}

Here is more info on available precompiled Elixir versions, branches and tags: GitHub - hexpm/bob: The Builder · GitHub

While I wrote this thinking about Elixir, it likely applies to most libraries out there.

22 comments

#official-elixir-notice

29 4787 22

2018-08-04 08:13:30 UTC

First Post!

josevalim

Creator of Elixir

Post #1

Most Liked

aseigo

Fun idea. Made it my evening project. GitHub - aseigo/hexagon · GitHub

Am running it on my laptop right now with Elixir 1.7.1 and Erlang 21.0.4 .. let’s see what happens. If the community feels it would be actually useful, I could run it regularly on servers at work. Could also extend it with other checks, e.g. perhaps harness credo to do some static analysis.

It is pretty bare-bones … perhaps logging with json would be nicer for later usage. Also just noticed it fails for rebar projects, which should be easy enough to fix. So rough edges, to be expected for a few hours thrown at a project, I guess .. improvements welcome

It has already found packages with problems, e.g.:

 == 23:15:30.197
FAILED at compile: /home/aseigo/packages/ex_loader/0.4.1
errors: could not compile dependency :pre_commit_hook, "mix compile" failed. You can recompile this 
dependency with "mix deps.compile pre_commit_hook", update it with "mix deps.update pre_commit_hook" 
or clean it with "mix deps.clean pre_commit_hook"

Neat.

edit: bonus round .. Since I had them on disk already, I ran cloc over the entire set of packages. https://exote.ch/~aseigo/state_of_hex.txt

Post #21

bbense

It might be nice to give people a reminder about the @moduledoc false convention. Or even better a tool that flags uses of private apis from the standard lib as a compile time warning.

Post #2

kelvinst

Also, it would really be nice to have at least a warning when a private API is being used by a module outside its application. I remember that being discussed somewhere else but don’t remember the outcome of it, maybe that’s not even possible, IDK.

Post #4

Last Post!

aseigo

Yes, if I get this working sufficiently well I will definitely reach out to the hex.pm team. It will be most useful if we can provide some feedback loops, including notice of build breakage, e.g.

Post #23