An Outsider's Guide To Julia Packages

From: andrew cooke <andrew@...>

Date: Mon, 31 Aug 2015 20:19:15 -0300

This is how I develop (or will develop) Julia packages.  Some of this is
documented at
but it doesn't include all the social stuff, and there's so much information
already there I thought a shorter, more opinionated, separate guide, that

1 Choose a name.  This is fun, but also fraught woth social danger.  You
want something short and memorable, but not so short and memorable that
it's considered "reserved" for "officially blessed" packages.  So, for

There are guidelines on naming in the official docs at
but they're more additional constraints you have to be aware of than help
with finding a GOOD name.

2  Create the package locally using Pkg (ie Pkg.generate("MyName", "MIT").  I
have no idea what other licences are available, or how you find out, but
you can edit the generated files and change the licence later, if you want.

3  That creates a directory in ~/.julia/vX.Y/MyName.  I typically work in
~/project/MyName, so at this point I make ~/project/MyName a soft link to
the .julia directory (ie ln -s ~/.julia/vX.Y/MyProject ~/project/MyName)

4   Write some code.  Types are CamelCase, functions and variables are lower
case with underscores ony when "necessary".

If it helps, I have written sme notes about how to structure Julia code:
http://acooke.org/cute/WritingCle0.html

5  Write some tests.  Run them with Pkg.test("MyName").

6  When you want to send the code to github, create the MyName.jl repo (don't
forget the ".jl") without any files (you need to do this by hand on
github).  Then you can push the code to github from the command line
(follow the instructions github displays after creating the repo -
depending on how carefully you set git up before (see first link) you may
not need to set the remote).

Note that you do not use Pkg commands above.

7  At this point you can configure Travis https://travis-ci.org to run your
tests each time you commit them to github.  The Pkg.generate() command
(above) already set things up - all you need to do is log on to Travis and
enable it there (the interface is not very intuitive, but if you persist
it's worth it because the little badge appears in the README, assuming you
left that code in place).

8  Eventually you may want to release the code to the wide world.  I tend to
do this quite soon - what's the point in keeping things quiet? - but you
make get helpful comments from the Julia people if they don't agree.

Anyway, you do this by following the instructions at

However, you may want to do things in the following order:
Pkg.update()  # make sure you have the latest metadata
Pkg.tag("MyName")  # tag release 0.0.1
Pkg.publish()
it's pointless to publish something without a version.

WARNING - tread carefully with what follows.

Pkg.publish() will give you a link, which you need to open in a browser.
That wikl take you to github where you can create a pull request.  Do this
step.

Once you have a pull request, wait.  Reload the page.  At first everything
will be green, but after a moment there'll be something orange/yellow
warning you that checks are pending.

At this point, if this is your first release (and not an updated version -
see below) then you STOP HERE.  Even when things turn green, YOU DO NOT
MERGE.  Instead, you wait for the Julia people to merge, after they have

9  However, if you have been peviously accepted, and are only merging after a
new release (ie Pkg.tag() and Pkg.publish() only) then YOU CAN merge, once
the orange/yellow thing has turned green.

Note that you should not tag a major release until Julia itself has
reached a major (ie 1.0.0) release.  I guess the logic is that you can't
guarantee that it is stable if the language is not stable (I have tagged a
1.0 release for a package, and it did work, but it also triggered a
helpful comment fom the Julia people).

10  If you are working with multiple Julia language versions, then you may find
that it's simpler for them all to chare the same code.  I do this as
follows:
- Create things in v0.4 as above, in ~/.julia/v0.4
- In julia-0,3, use Pkg.add("MyName") to get a copy in ~/.julia/v0.3
(and set the correct metadata locally)
- Then, by hand, remove the ~/.julia/v0.3/MyName directory and replace
it with a soft link to the ~/.julia/v0.4/MyName directory.  Julia
will not "notice", and you end up with both versions seeing the
same version of the code.  Then you can run the tests in either
version via Pkg.test().

11  Once your package appears at https://pkg.julialang.org/ (this takes some
time - the update process seems to be broken) then you can
I can see, so steal whatever someone else is using in their README.
See https://github.com/andrewcooke/ParserCombinator.jl for example.

12  Similarly, you can get code coverage results by using https://coveralls.io
This requires that you modify the .travis.yml file slightly.  Again, I
have no idea where this is documented, but you can steal from my file,
which I stole from someone else:
https://github.com/andrewcooke/ParserCombinator.jl/blob/master/.travis.yml
(it's the extra bits that mention Coverage and Coveralls).

And if you still get helpful comments from the Julia people, even after
following all the above, then feel free to blame me.

Andrew

Note: This post is updated occasionally.  The "Date" timestamp is when the
original was first posted.

Change: No Longer Possible To Merge Metadata

From: andrew cooke <andrew@...>

Date: Fri, 2 Oct 2015 15:45:34 -0300

As far as I can tell, it's now not possible to merge Metadata (step 9).
Instead, you just submit and wait.

At least, I can't see a "merge" button any more.

Andrew