[feat] improve docs on supported dependency versions #477

New issue

Open

opened 2023-02-18 14:24:50 +00:00 by flisk · 1 comment

flisk commented

2023-02-18 14:24:50 +00:00

Contributor

The idea

in order to make things easier for users and new contributors, i think it would be useful to:

define a minimum supported version for elixir, erlang and postgres, and test against these in CI
define a recommended version for elixir, erlang and postgres, test against these in CI and use them to build OTP releases and docker images
document these versions in a single place and refer to that place from the install docs and dev setup docs
whenever possible, automate/lint for updating of versions in things like Dockerfile and .woodpecker.yml so they won't fall out of date

The reasoning

i think it would be useful to mention clearly which versions of some core dependencies are explicitly supported and recommended for running and hacking on akkoma. i've found several different places in the docs and code that suggest different things:

the source-based install guides, which say to use elixir 1.12 or newer and postgres 9.6 or newer
the ci config, which seems to test and build against the latest major versions of elixir, erlang and postgres
the Dockerfile, which is built from elixir 1.13 and erlang 24.3 right now
a leftover elixir_buildpack.config with very old elixir and erlang versions (is this even used anymore? could this just be dropped?)

any thoughts? if this sounds like a good idea to you, i'd be happy to help implement it.

Have you searched for this feature request?

I have double-checked and have not found this feature request mentioned anywhere.
This feature is related to the Akkoma backend specifically, and not pleroma-fe.

### The idea in order to make things easier for users and new contributors, i think it would be useful to: * define a minimum supported version for elixir, erlang and postgres, and test against these in CI * define a recommended version for elixir, erlang and postgres, test against these in CI and use them to build OTP releases and docker images * document these versions in a single place and refer to that place from the install docs and dev setup docs * whenever possible, automate/lint for updating of versions in things like `Dockerfile` and `.woodpecker.yml` so they won't fall out of date ### The reasoning i think it would be useful to mention clearly which versions of some core dependencies are explicitly supported and recommended for running and hacking on akkoma. i've found several different places in the docs and code that suggest different things: * the source-based install guides, which say to use elixir 1.12 or newer and postgres 9.6 or newer * the ci config, which seems to test and build against the latest major versions of elixir, erlang and postgres * the `Dockerfile`, which is built from elixir 1.13 and erlang 24.3 right now * a leftover `elixir_buildpack.config` with very old elixir and erlang versions (is this even used anymore? could this just be dropped?) any thoughts? if this sounds like a good idea to you, i'd be happy to help implement it. ### Have you searched for this feature request? - [x] I have double-checked and have not found this feature request mentioned anywhere. - [x] This feature is related to the Akkoma backend specifically, and not pleroma-fe.

👍 1

flisk added the

feature request

label 2023-02-18 14:24:50 +00:00

ilja commented

2023-02-18 22:48:13 +00:00

Contributor

Personally I 100% agree because this has annoyed me as well.

I think, technically speaking, the supported Elixir versions should be what's defined in mix.exs (although I don't believe the currently defined version is still correct). But if we also want a central place for e.g. Postgresql, then the central place for documentation is the generic_dependencies.include.

On the long run I think the supported versions should depend on the installation guides. I.e. If we have an installation guide for Debian, then someone installing on a supported Debian should be able to do so. If we require different versions than what's available in the repo's, it should be clear how to check and how to work around it (e.g. for Elixir/Erlang that can be installing from a different source like erlang-solutions or asdf).

On the short term, it should be enough to figure out what versions are supported and align everything as described in the OP.

Personally I 100% agree because this has annoyed me as well. I think, technically speaking, the supported Elixir versions should be what's defined in [mix.exs](https://akkoma.dev/AkkomaGang/akkoma/src/branch/develop/mix.exs#L8) (although I don't believe the currently defined version is still correct). But if we also want a central place for e.g. Postgresql, then the central place for documentation is the [generic_dependencies.include](https://akkoma.dev/AkkomaGang/akkoma/src/branch/develop/docs/docs/installation/generic_dependencies.include). On the long run I think the supported versions should depend on the installation guides. I.e. If we have an installation guide for Debian, then someone installing on a supported Debian should be able to do so. If we require different versions than what's available in the repo's, it should be clear how to check and how to work around it (e.g. for Elixir/Erlang that can be installing from a different source like erlang-solutions or asdf). On the short term, it should be enough to figure out what versions are supported and align everything as described in the OP.