sheerlox

SemanticReleaseHex - Fully automated version management and release processes

Hello, Elixir community!

I’m excited to introduce a new tool that aims to streamline version management and release processes for Elixir projects: semantic-release-hex.

Disclaimers

Before we dive in, I want to clarify that semantic-release-hex is a JavaScript library designed to enhance version management and release processes in Elixir projects. While it’s not an Elixir library per se, its integration with Elixir projects can bring the power and simplicity of semantic-release to your workflow.

I also want to mention that although it’s only been two weeks, I’ve recently been invited to the semantic-release organization. The reason I’m developing this library is unrelated to my membership in the organization and is solely motivated by my complete trust and utter admiration for that project, which I’ve been using for more than 6 years in all of my projects, both personal and professional.*

Why?

In the course of developing a SaaS project with Elixir & Phoenix, I encountered the challenge of automating version management while adhering to best practices. Initially being a JavaScript developer, I turned to the reliable semantic-release tool but found it lacking in Elixir integration. This led me to create semantic-release-hex.

semantic-release features

Determining the next version number
Generating release notes & updating the changelog file
Creating a git tag
Publishing GitHub/GitLab releases
Commenting on released Pull Requests/Issues

semantic-release-hex features

Updating the version in mix.exs

semantic-release-hex roadmap

Updating the version in README
Updating the version in Mix.install/2 scripts
Distributed as a hex package (similar to tailwind)
Publishing to Hex

Benefits

Fully automated release
Enforce Semantic Versioning specification
New features and fixes are immediately available to users
Notify maintainers and users of new releases
Use formalized commit message convention to document changes in the codebase
Integrate with your continuous integration workflow
Avoid potential errors associated with manual releases
Simple and reusable configuration via shareable configurations

Trying it out

I’ve set up a demo repository to showcase what that would look like in an Elixir project: semantic-release-hex-demo. Feel free to explore its content, commit history, or even fork it to test things out, as it’s what it’s meant for.

You will also find detailed instructions on how to set it up in your own Elixir project on the main repository.

I’m eager to hear your thoughts, answer any questions, and discuss how semantic-release-hex can enhance your Elixir projects!

Also, if you’d like to share your views on features currently being specified/implemented, don’t hesitate to visit the Discussions/Issues for feature requests.

Thank you for reading

Acknowledgements

Special thanks to @Eiji and @D4no0 for their invaluable feedback!

https://github.com/unill-io/semantic-release-hex

https://github.com/sheerlox/semantic-release-hex-demo

15 comments

#library #release #semantic-versioning #cicd #semantic-release-hex

6 1904 15

2024-06-16 12:08:52 UTC

Most Liked

sheerlox

That all makes total sense, I now understand your point about having the documentation on hexdocs, which would be even further solidified by the creation of an Elixir package abstracting the installation and release mechanisms associated with Node.js. I really like this solution and have already started looking into it.

I’m not aware of any mention of a standalone release of semantic-release-cli, but that will be a great addition to the tool that I’m sure the core team will welcome with enthusiasm! I’ll run the idea by them while working on a prototype.

Regarding the AI-based documentation generator, semantic-release indeed does not ship with that feature, but maybe someone will create a plugin for that in the future

Thank you for being so patient with me, your input is really valuable and highly appreciated!

Post #6

thiagomajesk

I have used another lib called git_opts before, which is written in Elixir. Out of curiosity: did you find any specific functionality lacking in the ecosystem that prompted you to create another library?

Post #7

Eiji

Isn’t it easier to create a mix task which firstly guess based on configurable prefix (let’s say: "fix: ") and then asks for a type of version change giving the guessed one as default (to just press enter)?

config ::semantic_release, :prefix,
  major: ["…"],
  minor: ["…"],
  major: ["fix: ", "other: "],

Some projects would need to add node as extra environment dependency which is not always a good idea. If we are going to simplify one thing we shouldn’t complicate other one. For me it’s simple on my laptop, because I use asdf, but not everyone is in such case. Also obviously the documentation is not on hex with all of it’s side-effects which may be confusing especially for new developers.

$ mix semantic.release --log-level debug
[debug] Found "…" prefix in commit message which is configured for … version change
[debug] Found (…)
(…)
[info] The determined version change is …
Which version change should be applied?
1) Major
2) Minor
3) Bug fix (default)
Choose type of version change [1/2/3] _
[debug] The chosen type is …
[info] The new version is …
Are you ready to push changes [Y/n] _
[debug] Pushes commit(s)
Do you want to create a new git tag "v1.x.y"? [Y/n] _
[debug] Created git tag "v1.x.y"
Do you want to publish a release to hex? [Y/n] _
[debug] The release has been published
[debug] The documentation has been published
The version has been successfully changed from … to …

$ mix semantic.release --yes-all
Which version change should be applied?
1) Major
2) Minor (default)
3) Bug fix
Choose type of version change [1/2/3] _
The version has been successfully changed from … to …

$ mix semantic.release --yes-all --default
The version has been successfully changed from … to …

Does it have any strict format or it’s configurable somehow?

Does it creates a git tags automatically as well (git checkout v1.x.y or so)?

What is the comment content? Is it configurable? How about wiki?

For me the best documentation is:

wiki as user perspective
issue as developer perspective
pull request as implementation details

How about Installation in README.md file? It should be easy to find in markdown as long as you know the project name and previous version.

Those links are relative, so browser searches it on this forum …

Post #1

Last Post!

Eiji

Oh, right. Yeah, that part completely makes sense. I completely forgot about binaries. Look that hex packages and their documentation are saved globally in $HOME/.hex directory, so it could be a bit confusing for me.

Then I would say follow phoenix way i.e. generate package.json as described already, but also install binaries into _build directory.

Hmm … Now I see the point. Still prefer assets way, but maybe with some changes … assets/semantic_release?

Originally I was thinking (assuming same node_modules) that developers are familiar with basic npm stuff, because as said above it’s not really something new to add Node dependencies into Phoenix projects. That’s said it may not be best for new projects … If we would follow similar things then I would look for phoenix generators which instructs developers to add routing. Here instead of routes there could be adding or modifying existing alias i.e. assets.setup. It’'s just a copy-paste and assets.setup is part of most Phoenix projects. I guess every Elixir developer which does not started learning recently would get it easily.

Is that so? Not remember now how tailwind is doing that, but by default it fetches latest stable build, right? Modifying json files today is a piece of cake, so in worst case there should not be a problem with updating package.json file or maybe I have missed something again.

Also you worry about best case (actively maintained package). What about worst case (no support)? How would developers deal with possible updates? Look what have changed over years … Previously every Phoenix project was based on Webpack and now we have a completely new way i.e. esbuild.

Summary:

_build sounds really well for binaries especially if phoenix does the same thing (previously I was focused more on assets stuff)
Does something like assets/semantic_release, semantic_release or similar makes any sense?
package.json (regardless if creating in extra directory or shared with root project) is more intuitive for developers. Especially those who are new in Elixir. It’s simpler to understand well documented mix aliases than a source code of mix task in one of possibly many project dependencies.

Well … all above is not some kind of advice, but just some loose thoughts, so no need to consider everything. After what you wrote I’m no longer convinced with both node_modules in _build, in assets (shared with root project) as same as separate directory. My intuition tells me it’s something similar, but I have no idea what it might be exactly.

Right before posting I got a weird idea … apps/my_app_semantic_release/assets/node_modules or something like that, but it looks like I’m overthinking it a bit.

Post #15