From 54e90d44b0c58c1769c74dca8fca5346b9e91d7e Mon Sep 17 00:00:00 2001 From: "Paulo F. Oliveira" Date: Sun, 16 Jun 2024 03:13:54 +0100 Subject: [PATCH] Tweak `markdownlint` rules and README versioning (#286) --- .markdownlint.yml | 4 +++ CODE_OF_CONDUCT.md | 1 - CONTRIBUTING.md | 17 +++++---- LICENSE.md | 1 - README.md | 89 ++++++++++++++++++++++++++++------------------ 5 files changed, 70 insertions(+), 42 deletions(-) create mode 100644 .markdownlint.yml diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..90b8143 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,4 @@ +--- +default: true +MD013: + line_length: 100 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 4ecf822..ea11ad4 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,4 +1,3 @@ - # Contributor Covenant Code of Conduct ## Our Pledge diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b2f234..bc02ace 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,18 @@ - # Contributing [fork]: https://github.com/erlef/setup-beam/fork [pr]: https://github.com/erlef/setup-beam/compare [code-of-conduct]: https://github.com/erlef/setup-beam/blob/main/CODE_OF_CONDUCT.md -Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great. +Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for +keeping it great. -Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE.md). +Contributions to this project are +[released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) +to the public under the [project's open source license](LICENSE.md). -Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms. +Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By +participating in this project you agree to abide by its terms. ## Submitting a pull request @@ -23,13 +26,15 @@ Please note that this project is released with a [Contributor Code of Conduct][c Here are a few things you can do that will increase the likelihood of your pull request being accepted: - Write tests. -- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. +- Keep your change as focused as possible. If there are multiple changes you would like to make that +are not dependent upon each other, consider submitting them as separate pull requests. - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). - Execute `npm run build-dist` and fix any issues arising from that ## Running tests -When running tests locally, a valid classic GitHub token with the `repo` scope is required for tests to pass. +When running tests locally, a valid classic GitHub token with the `repo` scope is required for tests +to pass. - Export the token in the current shell: `export GITHUB_TOKEN=` - Run tests `npm test` diff --git a/LICENSE.md b/LICENSE.md index 8f60151..fb33ea9 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,3 @@ - # The MIT License (MIT) Copyright (c) 2019 GitHub, Inc. and contributors diff --git a/README.md b/README.md index 79a80f4..037ce51 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ - -# setup-beam [![GitHub Actions][action-img]][action] [![GitHub Actions][ubuntu-img]][ubuntu] [![GitHub Actions][windows-img]][windows] +# setup-beam [![Action][action-img]][action] [![Ubuntu][ubuntu-img]][ubuntu] [![Windows][windows-img]][windows] [action]: https://github.com/erlef/setup-beam/actions/workflows/action.yml [action-img]: https://github.com/erlef/setup-beam/actions/workflows/action.yml/badge.svg @@ -28,23 +27,44 @@ workflow by: See [action.yml](action.yml) for the action's specification. -**Note**: the Erlang/OTP release version specification is [relatively -complex](http://erlang.org/doc/system_principles/versions.html#version-scheme). -For best results, we recommend specifying exact +### Input versioning + +Input (tools') versions are controlled via `with:` (check the examples below). + +#### Strict versions + +The Erlang/OTP release version specification, for example, is [relatively +complex](http://erlang.org/doc/system_principles/versions.html#version-scheme), so, +for best results, we recommend specifying exact versions, and setting option `version-type` to `strict`. + +#### Version ranges + However, values like `22.x`, or even `>22`, are also accepted, and we attempt to resolve them according to semantic versioning rules. This implicitly means `version-type` is `loose`, which is also the default value for this option. +#### Specify versions as strings, not numbers + Additionally, it is recommended that one specifies versions using YAML strings, as these examples do, so that numbers like `23.0` don't end up being parsed as `23`, which is not equivalent. +#### Pre-release versions + For pre-release versions, such as `v1.11.0-rc.0`, use the full version specifier (`v1.11.0-rc.0`) and set option `version-type` to `strict`. Pre-release versions are opt-in, so `1.11.x` will not match a pre-release. -Use `latest` for the latest version; the latest version is calculated based on all the retrieved versions. Please take a look at the test cases for examples. +#### "Latest" versions + +Set a tool's version to `latest` to retrieve the latest version of a given tool. +The latest version is (locally) calculated by the action based on the (retrieved) versions +it knows (**note**: it is not the same as [GitHub considers it](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) +and some repositories might propose). + +If in doubt do a test run and compare the obtained release with the one you were expecting to +be the latest. ### Compatibility between Operating System and Erlang/OTP @@ -53,28 +73,29 @@ and Erlang/OTP. | Operating system | Erlang/OTP | Status |- |- |- -| ubuntu-18.04 | 17.0 - 25.3 | ✅ -| ubuntu-20.04 | 20.0 - 27 | ✅ -| ubuntu-22.04 | 24.2 - 27 | ✅ -| ubuntu-24.04 | 24.3 - 27 | ✅ -| windows-2019 | 21* - 25 | ✅ -| windows-2022 | 21* - 27 | ✅ +| `ubuntu-18.04` | 17.0 - 25.3 | ✅ +| `ubuntu-20.04` | 20.0 - 27 | ✅ +| `ubuntu-22.04` | 24.2 - 27 | ✅ +| `ubuntu-24.04` | 24.3 - 27 | ✅ +| `windows-2019` | 21* - 25 | ✅ +| `windows-2022` | 21* - 27 | ✅ -**Note** *: prior to 23, Windows builds are only available for minor versions, e.g. 21.0, 21.3, 22.0, etc. +**Note** \*: prior to 23, Windows builds are only available for minor versions, e.g. 21.0, 21.3, +22.0, etc. ### Self-hosted runners Self-hosted runners need to set env. variable `ImageOS` to one of the following, since the action uses that to download assets: -| ImageOS | Operating system -|- |- -| ubuntu18 | ubuntu-18.04 -| ubuntu20 | ubuntu-20.04 -| ubuntu22 | ubuntu-22.04 -| ubuntu24 | ubuntu-24.04 -| win19 | windows-2019 -| win22 | windows-2022 +| ImageOS | Operating system +|- |- +| `ubuntu18` | `ubuntu-18.04` +| `ubuntu20` | `ubuntu-20.04` +| `ubuntu22` | `ubuntu-22.04` +| `ubuntu24` | `ubuntu-24.04` +| `win19` | `windows-2019` +| `win22` | `windows-2022` as per the following example: @@ -96,13 +117,13 @@ jobs: The action provides the following outputs: -| Output | Content -|- |- -| otp-version | The Erlang version, e.g. `OTP-26.0` -| elixir-version | The Elixir version, e.g. `v1.14-otp-26` -| gleam-version | The Gleam version, e.g. `v0.23.0` -| rebar3-version | The `rebar3` version, e.g. `3.18.0` -| setup-beam-version | The commit unique id of the executed action version, e.g. `a34c98f` +| Output | Content +|- |- +| `otp-version` | The Erlang version, e.g. `OTP-26.0` +| `elixir-version` | The Elixir version, e.g. `v1.14-otp-26` +| `gleam-version` | The Gleam version, e.g. `v0.23.0` +| `rebar3-version` | The `rebar3` version, e.g. `3.18.0` +| `setup-beam-version` | The commit unique id of the executed action version, e.g. `a34c98f` accessible as `${{steps..outputs.}}`, e.g. `${{steps.setup-beam.outputs.erlang-version}}` @@ -125,12 +146,12 @@ with the following correspondence. #### `.tool-versions` format -| YML | `.tool-versions` | -|- |- | -| `otp-version` | `erlang` | -| `elixir-version` | `elixir` | -| `gleam-version` | `gleam` | -| `rebar3-version` | `rebar` | +| YML | `.tool-versions` +|- |- +| `otp-version` | `erlang` +| `elixir-version` | `elixir` +| `gleam-version` | `gleam` +| `rebar3-version` | `rebar` ### Example (Erlang/OTP + Elixir, on Ubuntu)