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
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
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.
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.
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
Once the installation is done it is time to clean! We can run it with the following commands
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
- 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!