Skip to content

Commit 42fe969

Browse files
sheerloxsheerlox
committed
docs(readme): add detailed setup guide and workflow examples
1 parent 47b8479 commit 42fe969

File tree

4 files changed

+227
-6
lines changed

4 files changed

+227
-6
lines changed

‎README.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,19 +13,20 @@
1313
> **Warning**
1414
> Publishing to `hex` has not yet been implemented, so this package only bumps the version in `mix.exs` for now.
1515
16-
| Step | Description |
17-
| ------------------ | --------------------------------------------------------------------------- |
18-
| `verifyConditions` | Verify the presence of the `mix.exs` file and that the version is parsable. |
19-
| `prepare` | Update the version in `mix.exs`. |
20-
| _`addChannel`_ | _to be implemented (PRs welcome)_ |
21-
| _`publish`_ | _to be implemented (PRs welcome)_ |
16+
| Step | Description |
17+
| ------------------ | -------------------------------------------------------------------------------------------------------- |
18+
| `verifyConditions` | Verify the presence of the `mix.exs` file and that the version is parsable. |
19+
| `prepare` | Update the version in `mix.exs`. |
20+
| _`publish`_ | _[to be implemented](https://github.com/talent-ideal/semantic-release-hex/discussions/14) (PRs welcome)_ |
2221

2322
## Installation
2423

2524
```shell
2625
npm install semantic-release-hex -D
2726
```
2827

28+
For a more detailed setup guide, see [**Setting up an existing Elixir project**](./docs/SETTING_UP.md).
29+
2930
## Usage
3031

3132
Add the plugin to the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) (see example below).

‎docs/SETTING_UP.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Setting up an existing Elixir project
2+
3+
## Before we begin
4+
5+
`semantic-release` uses git tags to determine the current version of a project, so you must make sure your latest version is tagged (and pointing to the right commit).
6+
7+
If you are using a different tag format than `v${version}`, see the [`tagFormat` option](https://semantic-release.gitbook.io/semantic-release/usage/configuration#tagformat).
8+
9+
## Install Node.js
10+
11+
You'll need Node.js `>=18.17`.
12+
13+
The recommended way to install it is with the [`asdf`](https://asdf-vm.com/) version manager (which also supports Elixir) by adding it to your [`.tool-versions`](./.tool-versions) and running `asdf install`.
14+
15+
Otherwise, you can [download it from nodejs.org](https://nodejs.org/en/download/).
16+
17+
## Install the tools
18+
19+
Install the required libraries:
20+
21+
```shell
22+
npm i --save-dev semantic-release @semantic-release/changelog @semantic-release/git semantic-release-hex
23+
```
24+
25+
Add `node_modules` to your `.gitignore`:
26+
27+
```shell
28+
echo -e "\n# Node.js dependencies directory\nnode_modules" >> .gitignore
29+
```
30+
31+
## Configuring `semantic-release`
32+
33+
`semantic-release` is [modular](https://semantic-release.gitbook.io/semantic-release/extending/plugins-list), [extendable](https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin) and [configurable to your preferences](https://semantic-release.gitbook.io/semantic-release/usage/configuration). Here we'll setup a workflow for the `main` branch with the following steps:
34+
35+
1. Analyze the commits to determine the version bump type (if any)
36+
2. Generate release notes from the commits
37+
3. Write the release notes to the `CHANGELOG.md` file
38+
4. Bump the version in `mix.exs`
39+
5. Create and push a release commit (with the updated `CHANGELOG.md` and `mix.exs` files)
40+
6. Create a release tag
41+
7. Create a GitHub release
42+
43+
There's [a few ways](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) to configure `semantic-release`, but we'll chose to do it in `package.json` to avoid creating an extra file. Add a `release` key as follow:
44+
45+
```json
46+
{
47+
"devDependencies": {...},
48+
49+
"release": {
50+
"branches": ["main"],
51+
"plugins": [
52+
"@semantic-release/commit-analyzer",
53+
"@semantic-release/release-notes-generator",
54+
"@semantic-release/changelog",
55+
"semantic-release-hex",
56+
[
57+
"@semantic-release/git",
58+
{
59+
"assets": ["CHANGELOG.md", "mix.exs"],
60+
"message": "chore(release): v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
61+
}
62+
],
63+
"@semantic-release/github"
64+
]
65+
}
66+
}
67+
```
68+
69+
_Note: if you want your CHANGELOG to include all commit types (and add a bit of color with category emojis) like the one in this demo, checkout [`@insurgent/conventional-changelog-preset`](https://github.com/insurgent-lab/conventional-changelog-preset#readme)_.
70+
71+
# CI configuration (GitHub Actions)
72+
73+
See [`semantic-release` documentation on CI configuration](https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations) for general information.
74+
75+
See [`examples/release.yml`](./examples/release.yml) and [`examples/test.yml`](./examples/test.yml) for example workflows in an Elixir project.
76+
77+
**If you use branch protection:** See comments in example release workflow. To generate the `CI_GITHUB_TOKEN` secret needed to bypass branch protection when pushing the release commit, see [this StackOverflow answer](https://stackoverflow.com/questions/74744498/github-pushing-to-protected-branches-with-fine-grained-token/76550826#76550826) on how to create a fine-grained token with the right scopes (I know, I really need to [update the docs](https://github.com/semantic-release/semantic-release/issues/2883)).
78+
79+
# Running from the CLI
80+
81+
_Note: If you're concerned about security, you can run `gh auth refresh` after using `gh auth token` to regenerate [`gh`](https://cli.github.com/)'s token and invalidate the previous one (or you can create a fine-grained token by visiting the StackOverflow link in [CI configuration](#ci-configuration-github-actions))._
82+
83+
## To test everything is working
84+
85+
```shell
86+
GH_TOKEN=$(gh auth token) npx semantic-release --dry-run
87+
```
88+
89+
## To make an actual release
90+
91+
```shell
92+
GH_TOKEN=$(gh auth token) npx semantic-release --no-ci
93+
```
94+
95+
_Note: if your git is configured to automatically sign tags, this won't work [due to a known issue](https://github.com/semantic-release/semantic-release/issues/3065). Run `git config tag.gpgSign false` in your repo first._

‎docs/examples/release.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- dev
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
test:
14+
uses: ./.github/workflows/test.yml
15+
permissions:
16+
contents: read
17+
18+
release:
19+
needs: test
20+
21+
# remove this if you use branch protection
22+
permissions:
23+
contents: write
24+
issues: write
25+
pull-requests: write
26+
27+
runs-on: ubuntu-latest
28+
29+
steps:
30+
- name: Checkout code
31+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
32+
# uncomment this if you use branch protection
33+
# with:
34+
# persist-credentials: false
35+
36+
- name: Use Node.js LTS
37+
uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4
38+
with:
39+
node-version-file: ".tool-versions"
40+
41+
- name: Install packages
42+
run: npm ci
43+
44+
- name: Audit npm signatures
45+
run: npm audit signatures
46+
47+
- name: Run Semantic Release
48+
run: npx semantic-release
49+
env:
50+
# replace the secret by CI_GITHUB_TOKEN if you use branch protection
51+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎docs/examples/test.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Test
2+
3+
on:
4+
push:
5+
# ignore branches where the release workflow runs as it already calls this one
6+
branches-ignore:
7+
- main
8+
pull_request:
9+
workflow_call:
10+
11+
permissions:
12+
contents: read
13+
14+
env:
15+
MIX_ENV: test
16+
17+
jobs:
18+
# ignore the push event trigger if a PR is open for the current branch
19+
prevent-duplicate-checks:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: insurgent-lab/is-in-pr-action@78ecb5daf15aca198aeb2b6f208aabd06b2cb716 # v0.1.4
23+
id: isInPR
24+
outputs:
25+
should-run: ${{ !(steps.isInPR.outputs.result == 'true' && github.event_name == 'push') }}
26+
27+
test:
28+
name: Build and test
29+
30+
runs-on: ubuntu-latest
31+
timeout-minutes: 5
32+
33+
needs: prevent-duplicate-checks
34+
if: ${{ needs.prevent-duplicate-checks.outputs.should-run == 'true' }}
35+
36+
steps:
37+
- name: Checkout code
38+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
39+
40+
- name: Set up Elixir
41+
uses: erlef/setup-beam@61e01a43a562a89bfc54c7f9a378ff67b03e4a21 # v1.16.0
42+
with:
43+
version-type: strict
44+
version-file: .tool-versions
45+
46+
- name: Restore dependencies cache
47+
uses: actions/cache@704facf57e6136b1bc63b828d79edcd491f0ee84 # v3.3.2
48+
env:
49+
cache-name: mix-deps
50+
with:
51+
path: deps
52+
key: ${{ runner.os }}-${{ env.cache-name }}-${{ hashFiles('**/mix.lock') }}
53+
restore-keys: ${{ runner.os }}-${{ env.cache-name }}-
54+
55+
- name: Restore build cache
56+
uses: actions/cache@704facf57e6136b1bc63b828d79edcd491f0ee84 # v3.3.2
57+
env:
58+
cache-name: mix-build
59+
with:
60+
path: _build
61+
key: ${{ runner.os }}-${{ env.cache-name }}-${{ hashFiles('**/mix.lock') }}
62+
restore-keys: ${{ runner.os }}-${{ env.cache-name }}-
63+
64+
- name: Install dependencies
65+
run: mix deps.get
66+
67+
- name: Check formatting
68+
run: mix format --check-formatted
69+
70+
- name: Compile code (without warning) and deps
71+
run: mix compile --warnings-as-errors
72+
73+
- name: Run tests
74+
run: mix test

0 commit comments

Comments
 (0)