[ANN] Introducing Upgradathon Fridays

Community
3

And here is how you do it!

First off, the process will be much simpler if you choose to drop support for Julia 0.6 on the master branch. Unless you have strong reason to create another release compatible with Julia 0.6 I would strongly recommend doing this, several packages, like StaticArrays and DataStructures, have already done so. If you need to release a 0.6 compatible bugfix release of your package you can do this from a branch later.

If your package are dependent on other packages, I suggest that you start with upgrading those first.

Before you start, check open pull request to the package to see if someone else has already made progress!

1. Obtain a copy of Julia v0.7

You can either do this by compiling from source (see the Julia README) but unless you want to wait, or are note comfortable with compiling yourself I suggest that you just download the latest nightly build from https://julialang.org/downloads/nightlies.html

2. Obtain the package source code

The first step is to put the source code that you want to upgrade in some local directory. I propose you take the chance to try out the new awesome package manager for this. In the Pkg REPL we can use the develop command to download the source code. Enter the REPL (with ] from the Julia REPL) and run

pkg> develop Foo

where Foo is the package we want to upgrade. By default, Pkg will now clone the repo, and put it in ~/.julia/dev/Foo. This is where we will make all our changes. I recommend that you make a branch before doing any edits to the source code (for example git checkout -b julia07fixes).

3. Run FemtoCleaner

The first step is to run FemtoCleaner which can do some, but not all upgrades automatically. You can use FemtoCleaner from GitHub (see FemtoCleaner usage HOWTO) but I will describe how to run it locally, since it is likely that you need to make other adjustments as well.

  1. First we need to update the Julia requirements for the package. This is what FemtoCleaner looks at when deciding which code rewrites that applies. Do this by changing julia 0.6 (or whatever is in there) to julia 0.7-alpha, then commit that change.

  2. Next we need to install FemtoCleaner. It is easier to run it from Julia 0.6. To install, open a Julia v0.6 prompt and run

    Pkg.clone("https://github.com/Keno/AbstractTrees.jl")
Pkg.checkout("AbstractTrees", "kf/for06")
Pkg.clone("https://github.com/JuliaComputing/Deprecations.jl")
Pkg.clone("https://github.com/JuliaComputing/FemtoCleaner.jl")

  3. Once the installation is done it is time to clean! We can run it with the following commands

    import FemtoCleaner
FemtoCleaner.cleanrepo("/home/fredrik/.julia/dev/Foo"; show_diff=true, delete_local=false)

    FemtoCleaner will now clone the repo to a temporary directory (the directory is printed to the screen), and upgrades whats in its power do to. When it is done the diff will be printed to the terminal. You can skip this, but it is good to have a look at what replacements FemtoCleaner did, in case you need to do some manual adjustments. After this you should go to the temporary directory, make a branch (git checkout -b femtocleaner), commit the changes (git commit -m "femtocleaning"), and push them back to your local repo (git push -u origin femtocleaner). In ~.julia/dev/Foo we can now pull in FemtoCleaners changes; either git cherry-pick the commit, or simply reset our branch to the femtocleaner branch that we just pushed (git reset --hard femtocleaner).

4. Run package tests

Now we can begin to test our package with Julia v0.7. We can test the package from the Pkg REPL:

pkg> test Foo

which will run the tests for Foo. It is likely that there will be deprecation warnings, and/or test errors. Look at the output and try to figure out what’s wrong. Fix them in the source code, and run the tests again. This is an iterative process, and hopefully the warnings are less the next time you pkg> test the package.

5. Push the changes and make a PR

When you are happy with the result, simply push the changes to the remote repo (git push -u origin julia07fixes where you might have to replace origin with your own fork unless you have commit priviliges to the original repo.) When the changes are pushed, create a pull request, and wait for CI to test your changes (don’t forget to remove Julia v0.6 from the CI configurations scripts!). If tests pass; Congratulations!, if not; try looking at the build logs to see what went wrong and fix up the last changes.

5. Some other tips

  • Line numbers from warnings and errors are not always 100% accurate, to improve the accuracy you can turn off inlining by starting julia with julia --inline=no.
  • Sometimes the deprecation warnings does not have any clue to where the error is, which makes it very difficult to find them. To get a full stacktrace to the warning you can start julia with julia --depwarn=error which will turn the deprecation warnings to errors. This prints a stacktrace and makes it much simpler to find.
  • Need help? Check out the Slack channel Keno mentioned in the top post, there are lots of willing people there to help you get rid of Julia 0.6!

Happy Upgradathon!

41 Likes