search

df-mc / dragonfly

Minecraft Bedrock Edition server software written in Go
https://discord.gg/U4kFWHhTNR
MIT License
669 stars 150 forks source link

Start recording changes in a change log #650

Open Sandertv opened 2 years ago

Sandertv commented 2 years ago

As discussed on Discord, we think it's a good idea to track changes per version in a change log. I'm personally a fan of Go's release note structure, but something like keepachangelog suggests a simpler changelog which is also an option. Feel free to suggest your ideas and preferences below.

As for when we start doing this, right now there is only 1 production user of Dragonfly, so maintaining change logs is probably not worth it yet. Once we get more users though, this is something to look into.

Until then, please post any suggestions below.

Thunder33345 commented 2 years ago

There's also Pocketmine's styled changelog which is a more structured approach to keepachangelog

dktapps commented 2 years ago

I wouldn't wait to start doing it. Better get into the habit of doing it now so that you have a good grip on how best to do it when you have more users.

Besides, having a changelog will help promote growth in the first place, since people will be more empowered to develop against alpha versions if there's a changelog to give them a TL;DR of each version rather than them having to dig through the code themselves.

SALLYPEMDAS commented 1 year ago

Can the changelog be generated automatically?

tristanmorgan commented 1 year ago

This one looks promising.... https://github.com/ldez/gcg

Thunder33345 commented 1 year ago

Can the changelog be generated automatically?

Changelogs are NOT commit logs, changelog should be a handcrafted log only containing what's useful to end user/developer, but keeps all the pointless noise out.

Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users. - Keep a Changelog: Can changelogs be bad?

So please don't use git commits as changelog, they defeats the point of having a changelog in the first place.

With that out of the way, it could be possible to generate changelogs, based on something, to produce a usable changelog that does not defeat the point of having a changelog in the first place, but in my opinion that will put more burden on contributors and maintainers on keeping some sort of machine readable commit for the changelog generator.

It would been easier if the changelog isn't coupled that deeply into the system affecting everyone else.