C[omp]ute

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
https://julia.readthedocs.org/en/latest/manual/packages/#package-development
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
includes all the helpful comments I've received, might be useful.

  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
    example, "Draw" was drowned with helpful comments, but "Drawing" was OK.

    There are guidelines on naming in the official docs at
    https://julia.readthedocs.org/en/latest/manual/packages/#guidelines-for-naming-a-package
    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".
    https://julia.readthedocs.org/en/latest/manual/style-guide/

    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").
    https://julia.readthedocs.org/en/latest/stdlib/test/

 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
    https://julia.readthedocs.org/en/latest/manual/packages/#tagging-and-publishing-your-package

    However, you may want to do things in the following order:
      Pkg.update()  # make sure you have the latest metadata
      Pkg.register("MyName")  # add it to your local metadata
      Pkg.tag("MyName")  # tag release 0.0.1
      Pkg.publish()
    so that you don't get helpful comments from the Julia people about how
    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
    reviewd your code.  They may give helpful comments instead of merging.

 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
    add a little badge to your README.  It's not documented anywhwere that
    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.