Displaying an update message

Hello everyone.

In a previous post about including a changelog in your repo, me and many others tried to argue how good it is for your users to have a changelog available to them.

This post is about yet another improvement of user experience: displaying a small message when updating a major version.

By “definition”, updating a major number almost certainly comes with very big changes. However, it is not always the case that a user will check every updated version one by one. What you can do instead, is display an update message when the user is using YourPackage for the first time. This message will be displayed only once, and now I will show you how to do it.

  1. In your gitignore add update*.
  2. At the end of YourPackage.jl file, add a section like:
if !isfile(joinpath(@__DIR__, "update_v2.0.0"))
\nUpdate message: DynamicalBilliards v2.0

This is the update message of my package.\n
"""; color = :light_magenta)
touch(joinpath(@__DIR__, "update_v2.0.0"))
  1. At major updates, or noteworthy minor updates, change the "update_v..." and the update text appropriately.

This approach does not depend on any “building” or “precompilation” process. It happens at using.

I suggest the following conventions for update messages:

  1. Start the update string with \nUpdate message: YourPackage version.
  2. Use the color :ligh_magenta: I think it is one of the least used at the moment, which would allow it to be established as “the update color standard”. I think it can be debated whether we want all the update string to be in magenta, or only the header (“update message…”). I don’t really know, go ahead and express your opinions!
  3. Add \n after your update message.

And that’s it. I hope this will be helpful for people like me that always wanted to display update messages in crucial releases!

This is how it looks when I first use my package:

This is how it looks the second time:


I haven’t tested yet what happens when one publishes a new release, e.g. 2.1 without changing the source of YourPackage.jl . I am not sure whether the existing touched file gets deleted on update or not…

But in any case, the good thing with this approach is that you can disable it on demand by commenting out the code upon new release tags.

Perhaps I missed something, but in Pkg3, AFAIK every new version will be in a different directory.

You are correct: DiffEqBase have been updated many times since I added it and in my \.julia\packages\DiffEqBase there are multiple folders. Well, at least the developer of YourPackage chooses when should this update message stop showing.

It is also good to add the file "update_v2.0.0" to .gitignore (e.g. /src/update_v* or something), otherwise this will make the repo dirty.

Yeah this is what my “step 1” does.

For anyone reading this, don’t follow the above approach, and instead see Use Scratch.jl for update messages · Issue #246 · JuliaDynamics/DrWatson.jl · GitHub