Maintaining a NEWS.md / CHANGES.md / ... file

[fingolfin]

The Julia registry now requires that major (= breaking) release of packages include release notes, with the idea that those should document what exactly is breaking, to give users of the packages a chance to adapt (or determine that they are already fine, beyond "tests pass, perhaps we are good???").

While I am always concerned about "forcing" such issues, overall I agree with the idea, and I really think we should consider starting to keep a basic curated changelog (NEWS.md or CHANGES.md or so) for AA, Nemo, Oscar and possibly more (we already do so for GAP.jl and have done so for a long time).

The goal is not to document every random change right and left, but at least the big ones, or at the very least, the breaking ones. Information like "type X was renamed to Y, the old name is still available but users should upgrade" are immensely helpful when trying to update code to a new version. E.g. if someone wrote code using Nemo or Oscar 1.5 years ago and is now trying to upgrade it, they will have a hard time (I helped people with this concrete problem not too long ago).

To reiterate: my goal is not to produce a ton of work by documenting every little detail; but surely we can (and need to) afford documenting at least major / breaking changes for the sake of our users (and in reality also for our own sake, as not everyone is always aware of what happens everywhere...)

[fingolfin]

Good background material & sensible guide on maintaining a useful changelog: https://keepachangelog.com/en/1.1.0/

[YueRen]

I don't mind having a CHANGES.md in the main folder and asking people to add a line to it whenever they do something noteworthy (e.g., breaking changes, new features, performance improvements, etc). However, we need think carefully how to organize said file to minimize the number of merge conflicts.

If you want to have proper curated release notes, we could simply advertise a call for items amongst the developers before every release.

[thofma]

I think it makes sense to document breaking changes. I am not quite sure how relevant this is for OSCAR in the foreseeable future, since 2.0 is long way off and we probably won't have breaking changes till then (by definition of 2.0).

[lgoettgens]

Do we want to include changes to experimental/ as well? Or just for code in src/?
If the former, it may make sense to split the release notes in two lists to separate this visually.