Add tags for releases about microlens HOT 11 CLOSED

hope you enjoyed the lecture

I did, thanks for the detailed explanation! The rationale of why a release was made and what risks it has definitely makes sense. Let me do this then:

• Update the changelog for the patch releases I just made. This will be uploaded with the next hackage release I make (whenever that is).
• Add shell scripts for version bumps which automatically add a TODO changelog entry so we remember in the future.

Thanks for your contributions and advice!

from microlens.

Sure, will do this for future releases.

from microlens.

I just realized, we have several different versions. How about tagging commits with the package + version, e.g. microlens-mtl-0.2.0.3? I'm assuming you want the tags so we can easily tell what changed between versions, is that right?

from microlens.

I just realized, we have several different versions.

Right, I didn't think of that.

How about tagging commits with the package + version, e.g. microlens-mtl-0.2.0.3?

Yes, this sounds good.

I'm assuming you want the tags so we can easily tell what changed between versions, is that right?

Indeed. git offers a lot of tools to do so easily if the tags are present.

from microlens.

I bumped the patch versions and created a new release for all the packages after your fix to the warnings. I tagged the versions in the repo, you can check here. How does it look?

from microlens.

Excellent, thanks!

from microlens.

Ah, looks like the latest entry is missing in the changelog, e.g. https://hackage.haskell.org/package/microlens-0.4.13.1/changelog : has no entry for 0.4.13.1.

I often spot such oversights for my own packages when I make a release candidate on hackage and then check out the rendering there, taking a small tour over the main page, the CHANGELOG, the docs...

There really should be some changelog linter checking such things, maybe there is something out there...

from microlens.

Maybe you made this mistake systematically, e.g. https://hackage.haskell.org/package/microlens-mtl-0.2.0.3 is also missing the entry for 0.2.0.3.

The changelog entry for a release basically explains (implicitly or explicitly) why this release is actually there (as opposed to being not there, not have happened after all). The why (which minimally is a list of fixes) is useful info for the developers that depend on it...

from microlens.

Apologies, I'm a bit new to this. My thinking was that the change only removes compile-time warnings but otherwise doesn't change any behaviors/dependencies/etc. , so I figured that it's fine to bump the patch version and not mention it in the changelog.

In general I don't know what should and shouldn't go in a changelog. Do you know of any guidelines? As another example, if I internally refactor some logic with no change in behavior, should that get mentioned? My thinking was no, even if I bump the patch version.

from microlens.

On the note of remembering to update the changelog, I was planning to add some shell scripts e.g. bump_minor_version.sh that would bump the version of the given package and also bump dependent packages if needed (based on what's listed here). Then I would also have that script add a TODO entry in the changelog so we don't forget.

from microlens.

Well, if you have no changelog entry for a released version, then the situation is ambiguous, because

1. you could have forgotten to add it (that is what folks naturally assume)
2. or, you deliberately didn't add it, but then folks still wonder why you even bothered to make that release, or why they should care.

If you don't know what should go into the changelog, it is helpful to put yourself into the position of your "customer". They mainly have two questions when it comes to a new version of their dependency:

1. What do I gain by using the new version?
2. What do I risk by using the new version?

So, in the present case it maybe was a patch release with just the compilation warnings removed. This is exactly what I as customer want to know! So, cosmetic gain with no risk that I am free to use or not, nothing to worry about, I can just let it happen. Perfect!

As a rule of thumb, a minimal changelog would list the issues closed and the PRs that landed (excluding the overlap). Of course, if there are API changes, these should be explained (but then you also need a major version bump (or at least a minor bump if things were only added).

My thinking was that the change only removes compile-time warnings but otherwise doesn't change any behaviors/dependencies/etc. , so I figured that it's fine to bump the patch version

Good thinking!

and not mention it in the changelog.

Bad thinking! ;-)
We still want to know what happened.

In general I don't know what should and shouldn't go in a changelog. Do you know of any guidelines?

Well, I am sure the net is full of advice and tutorial if you google around a bit. I have tried to justify it to you from a high-level perspective. If it comes to a recipe: link to all the issues and PRs, and try to find nice concise description of the changes.

As another example, if I internally refactor some logic with no change in behavior, should that get mentioned? My thinking was no, even if I bump the patch version.

Good question. If everything goes right, then it would be safe to not mention it. But we all know, we think we just have refactored something, but then months/years later a bug report comes in demonstrating we broke something.

In general, it has hardly been a problem in software development that people document too much. If you know a community where this happens, please get me in contact, because I want to study them. They can't be my usual colleagues, because everyone I know documents too little (not even that, rather way too little). They must be from another planet.

I think it depends a bit on the package:

1. If the package is experimental with frequent changes, I wouldn't bother to document refactorings, because no could follow the story reasonably if things are changing back and forth all the time.
2. If the package is stable, then yes, think twice whether you want to refactor (are the gains worth the risks of breaking something), and also document it in the changelog.

(Ok, this was me with my teacher hat on, hope you enjoyed the lecture.)

from microlens.