005: How (And When) to Publish a Package

What is an Elm Package?Elm package repositoryElm packages enforce SemVer for the public package APIThe SemVer (Semantic Versioning) SpecInteresting note: the SemVer spec says breaking changes only refers to the public API. But a core contributor clarifies that breaking changes can come from changes to the public contract that you intend users to depend on. See this GitHub thread.list-extra packagedict-extra packageMinimize dependencies in your package to make it easier for users to manage their dependencies"Vendoring" elm packages (using a local copy instead of doing elm install author/package-name) can be useful in some cases to remove a dependency from your packageShould you publish a package?The Elm package ecosystem has a high signal to noise ratioElm packages always start at version 1.0.0SemVer has different semantics before 1.0.0 (patch releases can be breaking before 1) - see SemVer spec item 4Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.Elm package philosophy is to do an alpha phase before publishing packageKeep yourself honest about solving meaningful problemsStart by asking "What problem are you solving? Who are you solving it for?"Scratch your own itchelm-graphqlservant-elm (for Haskell servant)Keep yourself honest about solving problems by starting with an examples/ folderEarly elm-graphql commits started with examples before anything elseWrite meaningful test cases with elm-testelm-verify-examplesHave a clear visionAsk people for feedbackLet ease of explanation guide you to refine core conceptsMake it easy for people to understand your package goals and philosophyInclude code examples in readme and docs to make it easier for people to get startedelm-review live stream videoUse meaningful examples solving concrete problems (images/screenshots are good, too)Richard Feldman's Exploring elm-spa-example talkLuke's elm-http-builder packageelm-spa-example's custom http request builder moduleInstead of writing a package, in some cases it could make sense to publish a blog post to share a patternPorting libraries vs. Coming Up With an Idiomatic Solution for ElmInstead of moment js ported to Elm, have an API built for a typed contextRyan's date-format packageHow to design an Elm package APIDefine your constraints/guarantees, make impossible states impossibleCharlie Koster's Advanced Types in Elm blog post seriesAvoid exposing internals of your dataElm Radio episode 002: Intro to Opaque TypesPay attention to how other packages solve problemsRichard Feldman's talk The Design Evolution of elm-css and elm-testBrian Hicks' talk Let's publish nice packagesLook at prior art, including in other ecosystemsLook at github issues and blog posts from projects in other ecosystemsPick your constraints instead of trying to solve every problemHelps you choose between tradeoffsHaving clear project goals explicitly in your Readme makes it easier to discuss tradeoffs with users and set expectationsIdiomatic elm package guide has lots of info on basic mechanics and best practices for publishing Elm packagesThe mechanics of publishing an elm packageelm make --docs docs.json will tell you if you're missing docs or if there are documentation validation errorselm-doc-previewCan use elm-doc-preview site to share documentation of branches, or packages that haven't been published yetSet up a CIDillon's CI script for dillonkearns/elm-markdown packageDillon's elm-publish-action GitHub Action will publish package versions when you increment the version in your elm.json - nice because it runs CI checks before finalizing a new package releaseelm publish will walk you through the steps you need before publishing the first version of your Elm package#packages channel on the Elm slack shows a feed of packages as they're published#api-design channel on the Elm slack is a good place to ask for feedback on your API design and package ideaContinue the ConversationShare your package ideas with us @elmradiopodcast on Twitter!