Refer to git-cliff documentation
orhun opened this issue · comments
I realized the following docs are the same as git-cliff docs:
- https://release-plz.ieni.dev/docs/changelog-format
- https://release-plz.ieni.dev/docs/config#the-changelog-section
These pages have the potential of getting outdated pretty easily so I suggest we refer to git-cliff documentation instead. e.g. if I add a new field or change some behavior, you also need to update these if you use the latest version of git-cliff.
I have some plans regarding improving the documentation of git-cliff:
Hey Orhun,
I did this on purpose. I know it's not ideal, but referring to the git-cliff docs has the following issues:
- Git-cliff might update their docs with new features that aren't in release-plz yet. E.g. now there's the GitHub integration that release-plz doesn't support yet. If users see a feature in git-cliff docs, they would expect it to work in release-plz too immediately.
- This page differs from git-cliff docs, because I only included the git-cliff options that make sense for release-plz. If you look closely there are some git-cliff fields that are missing.
- I find it confusing for users to jump between two different websites because it's hard to understand which parts of git-cliff are relevant for release-plz. So I prefer to copy paste the relevant part, explicitly saying that release-plz uses git-cliff for changelog generation, so that people can always go to the git-cliff website if something isn't clear.
I still try to link to the git-cliff website when I think it makes sense. For example, here I link to the awesome git-cliff examples :)
I hope this makes sense to you. Let me know if you still have any feedback or concerns.