How to publish an Elm package guide

Intro

This guide is focused on the mechanics on how to publish a new Elm package at https://package.elm-lang.org/, for more in-depth details please check the Real Life section.

Step 1 - Preparation

For publishing a new Elm package we need to ensure we have an elm.json file configuration similar to this:

{
    "type": "package",
    "name": "TheBestDeveloper/my-first-elm-package",
    "summary": "A sample Elm package reference",
    "license": "BSD-3-Clause",
    "version": "1.0.0",
    "exposed-modules": [
        "MyMath.FourierCalc",
        "MyMath.FrontierCalc"
    ],
    "elm-version": "0.19.0 <= v < 0.20.0",
    "dependencies": {
        "elm/core": "1.0.0 <= v < 2.0.0",
        "elm/html": "1.0.0 <= v < 2.0.0"
    },
    "test-dependencies": {}
}

The type of the project should be package since normal application projects are not allows as libraries at https://package.elm-lang.org/.

The field name contains the full Elm package name including the owner separated by an slash /, the owner should be a valid GitHub account you own.

Decide which license to use and add its code to the field license and its content to the file LICENSE including the fullname of the project owners.

The recommended license to use is BSD3, but of course you can use any license you want, a non-exhaustive list of possible licenses to use can be found at https://opensource.org/license.

For the initial version use 1.0.0 and the next versions will be calculated automatically by the system based and how deep are the evolution of the changes of your package along time.

Add a good summary using less than 80 characters.

Ensure the Elm version and dependencies version is under a valid range your packge library supports, here we are using Elm 0.19.x and elm/core and elm/html as a reference.

Then decide which modules you want to expose as part of the public API of your new package with entries at exposed-modules, you do not need to make all your modules public, try to expose as little as possible.

Include a README.md file at the root of your project with good documentation and useful examples.

Finally, you should document all of the publicly exposed modules and functions, here a guide about the documentation format to use -> http://package.elm-lang.org/help/documentation-format.

Step 2 - Clean, Compile and Test

With the new package configuration and README.md file in place then clean and compile your project from scratch ensuring the tests run successfully.

Step 3 - Publish the first version

Ensure all your code, documentation and configuration files are commited at GitHub and then tag it with the first version 1.0.0 using the commands:

git tag -a 1.0.0 -m "Initial release"
git push --tags

Now using this new tag, let's publish your new Elm package with the command:

elm publish

And that's it !! ... if you have all the requisites fullfiled, your new package will be published at https://package.elm-lang.org/.

If a requisite is not met of you found an error please double check the prepartion and compilation step and tune your package and try again.

Publish new versions

Once you have your first version published, a long the time you may require to add new features or fix possible bugs, for that just create new commits with the changes and then checking all the requisites as before, run the command:

elm bump

This will check your code and decide the new version following the rules of semantic versioning which normally creates a patch version on small changes and minor or even mayor version for more involved changes, but once again, all of this is calculated automatically and saved at your elm.json file.

If you want to inspect what are the changes and try to keep the versioning more fine grained run the command elm-package diff for getting more information about the new version automatic calculation process

With a new version calulated automatically, just clean, compile and test your project as before and then create a new tag at your repo using the new version with a command like:

git tag -a 1.0.1 -m "Adding a new feature"
git push --tags

Replace 1.0.1 with your previously automatic calculated version and give a more using tag comment

Then publish your new updated version with the command:

elm publish

Real life

Creating good packages requires more than just these mechanical steps, please visit Dillon Kearns in-depth publish tips at the Idiomatic Elm Package Guide

Some tips about new packages design can also be found at https://package.elm-lang.org/help/design-guidelines by Evan Czaplicki.

The original guide can be found at the history commits of the old elm-package repo found at https://github.com/elm-lang/elm-package created by Evan Czaplicki