Skip to content

Latest commit

 

History

History
111 lines (93 loc) · 4.96 KB

8-09_releasing-a-library.asciidoc

File metadata and controls

111 lines (93 loc) · 4.96 KB
Raw

Releasing a Library to Clojars

by Ryan Neufeld; originally submitted by Simon Mosciatti

Problem

You’ve built a library in Clojure, and you want to release it to the world.

Solution

One of the easiest places to release libraries to is Clojars, a community repository for open source libraries. To get started, sign up for an account. If you don’t already have an SSH key, the GitHub guide "Generating SSH Keys" is an excellent resource.

Once you have an account set up, you’re ready to publish any Leiningen-based project. If you don’t have a project to publish, generate one with the command lein new my-first-project-<firstname>-<lastname>, replacing <firstname> and <lastname> with your own name.

You can now use the command lein deploy clojars to release your library to Clojars:

$ lein deploy clojars
WARNING: please set :description in project.clj.
WARNING: please set :url in project.clj.
No credentials found for clojars (did you mean `lein deploy clojars`?)
See `lein help deploy` for how to configure credentials.
Username: # (1)
Password: # (2)
Wrote .../my-first-project-ryan-neufeld/pom.xml
Created .../my-first-project-ryan-neufeld-0.1.0-SNAPSHOT.jar
Could not find metadata my-first-project-ryan-neufeld:
    .../0.1.0-SNAPSHOT/maven-metadata.xml \
    in clojars (https://clojars.org/repo/)
Sending .../my-first-project-ryan-neufeld-0.1.0-20131113.123334-1.pom (3k)
    to https://clojars.org/repo/
Sending .../my-first-project-ryan-neufeld-0.1.0-20131113.123334-1.jar (8k)
    to https://clojars.org/repo/
Could not find metadata my-first-project-ryan-neufeld:.../maven-metadata.xml \
    in clojars (https://clojars.org/repo/)
Sending my-first-project-ryan-neufeld/.../0.1.0-SNAPSHOT/maven-metadata.xml (1k)
    to https://clojars.org/repo/
Sending my-first-project-ryan-neufeld/.../maven-metadata.xml (1k)
    to https://clojars.org/repo/

  1. Enter your Clojars username, then press Return.

  2. Enter your Clojars password, then press Return.

After this command has completed, your library will be available both on the Web (https://clojars.org/my-first-project-ryan-neufeld) and as a Leiningen dependency ([my-first-project-ryan-neufeld "0.1.0-SNAPSHOT"]).

Discussion

Releasing a library doesn’t get much easier than this; just create an account and press the Big Red Button. Together, Leiningen and Clojars make it trivially easy for members of the Clojure community such as yourself to release their libraries to the masses.

In this example, you released a simple, uniquely named library with little care for versioning, release strategies, or adequate metadata. In a real project, you should pay attention to these matters to be a good open source citizen.

The easiest change is adding appropriate metadata and a website. In your project.clj file, add an accurate :description and :url. If you don’t have a website for your project, consider linking to your project’s GitHub page (or other public SCM "landing page").

Less easy is having consistent version numbers for your project. We suggest a scheme called Semantic Versioning, or "semver." The semver scheme prescribes a version number of three parts, major, minor, and patch, joined with periods. This ends up looking like "0.1.0" or "1.4.2". Each version position indicates a certain level of stability and consistency across releases. Releases sharing a major version should be API-compatible; bumping the major version says, "I have fundamentally changed the API of this library." The minor version indicates when new, backward-compatible functionality has been added. Finally, the patch version indicates when bug fixes have been made.

It certainly takes discipline to follow Semantic Versioning, but when you do, you make it easier for your fellow developers to understand your library versions and trust them to behave in a way they expect.

Code signing is another important concern in the deployment process. Signing the artifacts you release lets your users know the artifacts were created by someone they trust (you) and contain exactly what you intended (i.e., they have not be tampered with). Leiningen includes the facilities to sign release artifacts using GPG and include the relevant .asc signature files in lein deploy publications. Enabling code signing is described in the GNU Privacy Guard (GPG) section of Leiningen’s deploying libraries guide.

See Also

  • The Clojars wiki, a bountiful source of information on releasing libraries to Clojars

  • Leiningen’s own deploying libraries guide, which covers code signing and how to deploy to repositories other than Clojars

  • The output of the lein help deploy command