Please, consider putting up a CHANGELOG file after moving to 0.7

Datseris · July 18, 2018, 8:47am

Hi everyone that is currently updating to 0.7.

I am also updating to 0.7 I have to admit that there definitely are some breaking changes that are happening in the packages I am updating. But of course, I am not special in any way. Breaking changes are happening all over the place in many packages.

I kindly ask the developers of packages to put up some kind of CHANGELOG.md/NEWS.md file, or anything related like a blogpost, that can list changes done, especially breaking ones. I am aware that this can be done via e.g. depwarnings as well, however it is clearly not as efficient for the user. This requires truly minimal effort, yet will have tremendous impact on people that were using your package on 0.6 and want to do so as well in 0.7.

I sincerely do not understand why many repositories do not do this. To the best of my knowledge, quite unfortunately, there is no way to print changes on package installation/update via the package manager. (see https://github.com/JuliaLang/julia/issues/16187, Printing changelog upon package updates).

kristoffer.carlsson · July 18, 2018, 8:54am

While having a changelog is good, the reason for this post (the DataFrames issue) seems misguided.
Renaming a field in your struct is not a breaking change (unless it was documented to be used). Use the official documented API (which is usually what is tested) and you’ll be happier.

Datseris · July 18, 2018, 9:03am

Please, let’s keep this discussion away from the DataFrames post. I’ve also deleted this part form the OP. I sincerely do not want this post to have anything to do with specific issues, or specific repositories. You are totally free to think that I am wrong about the issue (which I am), and I am totally free to think that “you” are wrong for not documenting it (which you are in my eyes), but for this post let’s focus on the serious issue, which is:

Most Julia packages repositories do not have a CHANGELOG/NEWS with lists of changes

p.s.: I Am indeed honest, this post here is totally not about the DataFrames issue: I have been thinking about this every time I update packages. And I see version numbers go up and up. Yet, I always wonder: was there anything breaking in these updates? I’d really, really like to know, but it is so damn hard!

Tero_Frondelius · July 18, 2018, 9:12am

Keeping CHANGELOG or similar requires effort. That effort is away from something else. I am 100% sure that you will get CHANGELOG (or any other feature) if you are willing to pay for it. There is always the option do it yourself but it won’t help here unless you will be able to provide automated solution like the extension to the Attobot.

This platform provide a way to pay: https://www.bountysource.com

Datseris · July 18, 2018, 9:16am

This effort is spent to keep users using your package though! Because if I as a user, update something, and my code doesn’t work, and it is truly impossible for me to find a list of changes, I will decide that the developers simply do not care about users, and use a different package.

It is crazy how developers don’t consider this… It will take you literally 2 minutes to also add a change into a changelog after you just did it. How much of an effort is that?

I mean, okay of course you can say that “I am developing just for myself, and I put it on GitHub”. That is also fine. But then shouldn’t there be some care about what packages a julia user should install and which are “not developed for users” ?

Tero_Frondelius · July 18, 2018, 9:20am

My understanding is that currently all Julia packages are developed for developers. All packages would like to attract more developers and they don’t care users at all. Game will change if you start paying to use the package(s).

Datseris · July 18, 2018, 9:22am

no, sorry, this is totally wrong. Look at JuliaDiffEq for example. Where a proper list of changes is always stated via a form of a blog post. In fact, there are many Julia packages that are aimed at users already, this is not a privilege of DiffEq. Another example is GitHub - JuliaMusic/MIDI.jl: A Julia library for handling MIDI files.

Tero_Frondelius · July 18, 2018, 9:33am

Ok you found some good examples but I will keep my opinion. I personally believe unit testing and if you have properly tested your package you won’t need the CHANGELOG information anyways. You Google the error and fix it and move on.

Tamas_Papp · July 18, 2018, 9:39am

I tend to agree with @Tero_Frondelius. Breaking changes should be indicated by bumping the major version. Users of a package should always restrict to a specific major version by default. Now with Pkg3 this becomes possible for projects, too.

jonathanBieler · July 18, 2018, 9:50am

I’ve been updating Gtk.jl and I think we should write some sort of changelog for it, since there’s some breaking changes and new functionalities that are hard to know about unless you read a 40 messages long issue, or read all the commits.

The “it takes time” argument doesn’t work popular for packages, because 1 minutes of your time will save say 10 minutes of time for other people (that are developers of other packages), so doing it will save time overall. Of course it depends on popularity and severity of the changes.

Tero_Frondelius · July 18, 2018, 9:50am

Exactly like @Tamas_Papp said and remembering this:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Tero_Frondelius · July 18, 2018, 9:55am

This I agree. I still consider writing a CHANGELOG a good habbit but I am questioning if anybody actually read those or should better testing exist instead of CHANGELOGs. I already admitted that I don’t read CHANGELOGs. I am not the best reference user because I don’t code that much myself.

ChrisRackauckas · July 18, 2018, 2:47pm

But if you bump a major version, it’s nice to tell someone what you broke and how to proceed.

Tamas_Papp · July 18, 2018, 5:07pm

Certainly. But in simple cases the deprecation mechanism should be sufficient. It works for most of the changes in Base, for example.

Many projects are maintained by a handful of people, with finite resources, so keeping a CHANGELOG takes time away from other things, or slows down the project. I strictly prefer the following to people maintaining a changelog:

clean and organized code, so I can contribute and fix things myself,
tons of unit tests and 90+% coverage,
extensive and detailed documentation,
deprecation paths and adherence to the concepts semantic versioning,
up to date tutorials and example problems.

When it comes to breaking changes, the following is a good compromise for me:

things should not intentionally break without incrementing the major version number,
if they break, I see deprecation messages (ideal), or the program terminates with an error (less than ideal, but OK). Just proceeding but doing something different is bad.

NaOH · July 18, 2018, 5:26pm

Perhaps it could be a good idea to add a blank CHANGELOG.md to the automatically generated package skeletons. This way it could become increasingly a standard.

NaOH · July 18, 2018, 5:27pm

Isn’t a changelog part of extensive and detailed documentation?

Not long ago one could hear the same about unit tests and documentation in general (they take time from the dev, whom could be rather writhing more (undocumented/untested) code).

This is something that can not be enforced, but perhaps just recommended. If people see a default changelog in the package skeletons, they may start using it, don’t you think?

Tamas_Papp · July 18, 2018, 5:48pm

No, not for me. It has a nontrivial maintenance cost (when not generated automatically from commits, but then it is pretty useless), and it is not that useful. The history of minor changes is pretty irrelevant for most users. Many projects stopped doing it; AFAIK GNU still insists on it though.

A NEWS file can be useful for large projects with major releases that span years (eg Julia), but then it is rewritten for each major release. In contrast to a CHANGELOG, what happened before the last major release is not kept (but of course can be dug up from version control).

airpmb · July 18, 2018, 6:43pm

Interesting discussion and I think each of you has a very valid point of view.

At the risk of just saying something that’s redundant to the ’s that I’ve clicked on some posts let me provide what might be another perspective on the topic.

TL;DR: Having changelogs, even if empty at first may 1. help people decide to become involved at all in package use and/or development; and 2. have a positive feedback effect where helping maintain a CHANGELOG helps make a NEWS file (or blog post or whatever) easier to contribute to, which in turn helps with #1, etc.

Details if you care to spend the time below:

Where I’m coming from is someone who is, I think, a pretty capable user of, and sometimes developer in most languages I’ve encountered. Though unfortunately not yet much development that’s open source in general of Julia in particular. This is not for lack of desire or ability (well, that last is debatable…) but priorities have just dictated that most of my development work has been for my employers and it hasn’t been able to be open source for various reasons.

Anyhow, I’d like to point out that the changelog file serves not only to help those that are already users/developers of a particular package but also those that might like to become so, but only once they deem that to be appropriate for them. And this can be a bit of a chicken/egg scenario if making that determination requires a level of knowledge of the package that extends to being able to understand a set of commit messages.

So the changelog file, as I think it’s been pointed out already (so sorry to perhaps simply be echoing), can serve to help in that determination and thus attract more usage of, and sometimes contribution to, a package/project.

Also, I’ll point out that there are probably many like myself who really would like to contribute to development, even if only in some small way. And initially a small way may be all we are capable of, or can justify to ourselves; in other words not significant core development, but perhaps documentation in some form. In such cases if the core developers don’t deem it to be worthwhile to maintain a changelog file themselves, perhaps it would be worthwhile to have the file in their repo (if only in a non-master branch) such that it could be contributed to by one of these what I’ll call ‘non-technical’ contributors. In turn when there is a changelog it also is easier to contribute to a NEWS file if you’re not a core dev and that again can core devs up to keep their focus on where they alone can make the most useful progress. I think everyone may benefit thereby.

I won’t try to tell the developers whether considering this perspective should make a difference to them in a way that should convince them to add and maintain a changelog file. I don’t pay for their time so it’s not my call, at all. But to the extent that these points are something they perhaps haven’t given thought to, I hope the above might be helpful.

Finally let me add a +1 to simply including CHANGELOG and NEWS files in the skeleton packages generated by Pkg. Kahneman et. al. say this is a good idea.

Thoughts?

P.S. The next thing I’m going to do after hitting send is to go add (empty) CHANGELOG and NEWS files to my little repo

… Edit: Along the way I came across this wonderful resource: https://keepachangelog.com/

giordano · July 18, 2018, 8:57pm

Keeping a ChangeLog/NEWS.md doesn’t seem to me much more work than writing deprecations. I’m the only contributor of most packages I work on, and I never feel like I’m wasting my time when I update the NEWS.md file. This is not only about deprecations, it’s about informing your users who don’t follow the development about what changed at all. In additions, deprecations are not useful if you jump a “major” version of the package.

I also tend to copy the content of NEWS.md to the description of the tag on GitHub. You don’t know how many times I wished other package maintainers did the same when they dropped support for a Julia version. No, it’s no fun to discover this information by looking at METADATA.jl.

Ward9250 · July 26, 2018, 3:17pm

We’ve started doing this and adding other project files such as HUMANS.md over at BioJulia.