How to publish an Elm package

This document tells you how to manage git commands for publishing in Elm 0.19. If you want a more comprehensive guide to writing packages, see here.

TL;DR (replace 2.0.0 with the right version):

git checkout master
elm bump
git add elm.json
git commit -m "2.0.0 - description of changes"
git tag 2.0.0
git push origin master 2.0.0
elm publish

Publishing an Elm package to the package catalog is a multi-step process, mostly because the Elm tooling doesn’t try to automate the necessary git commands. This is a quick-and-dirty reference that already assumes you have a GitHub repo and elm-package.json set up.

But first, if you are sending a pull request to a package, never bump the version field in elm.json. Let the package maintainer do that themselves, when they are ready to release.

So if you are the maintainer, what does a release look like? The central idea is that you make a commit where the version field of elm-package.json is updated (and nothing else), and that commit becomes the release. This commit should be made against master directly (git checkout master). (The only exception is if you’re updating a package for a prerelease of Elm, but that’s an expert topic.)

The most important preparation is make sure that all the code you want to be in the release is actually there. If you merge a pull request on GitHub, run git pull to get the changes locally. If you’re doing a major release, you should think really hard about whether there’s any other breaking changes you want to include. If you have a changelog or update guide, you should update them and commit the changes. Do a once-over of the README and make sure there isn’t any outdated information. You can also run elm diff to see what API changes are being made. Finally, run the compiler and your test suite.

Once that’s all done and you’re sure you have no uncommitted changes (run git status to be sure), run elm bump to change the version field in elm-package.json in accordance to Elm’s semantic versioning rules. This will also run the compiler in case your forgot. Next, we commit this change by running git add package.json and git commit. I recommend starting the commit comment with the name of the version you’re releasing (the bump command will tell you), followed by a dash and a short description of what happened in the release. For example,

git commit -m "2.1.0 - add Spline.reticulate"
git commit -m "2.1.1 - fix bug in Spline.reticulate"

This gives us a commit, but we need to tell GitHub that this commit is special. We do that that by “tagging” it, e.g. git tag 2.0.0. If you do this right after committing the change to elm-package.json, it will be that commit that gets tagged, which is exactly what you want. The name of the tag should, of course, be the version you’re releasing.

Then you need to push the tag, and the new commit to master, to GitHub. You don’t want to get into a weird state where the tag is pushed but master isn’t updated, and then try to commit something to master later! There are various flags to git push that push tags, or supposedly push tags and branches, but I haven’t have much luck with them. What works every time is to be explicit and list both things you’re pushing: git push origin master 2.0.0 will do the trick.

Finally, don’t forget to actually publish your package to the registry with elm \ publish so people can use it. I’ve forgotten this step more times than I’d like to admit.

Happy publishing!