Generate changelog for initial release
diazona opened this issue · 7 comments
I figured that even though this is supposed to be wrapped up as part of the release process, making an issue for this is probably a good way to help make sure we don't forget to do it. Basically this just entails running towncrier (see #88), but given that it's the first release, we might want to manually edit in some extra changelog entries (or backfill changelog fragments for a bunch of the changes that were already merged, if that makes more sense) to give a more thorough overview of the package's development history.
Of course the generation of the changelog does not itself need a changelog fragment 😄
@diazona This will be for release 1.0.0 I presume or are we releasing this as a pre-1.0 version number given its "alpha" status?
Oh I was going to go for 0.1. Mostly just because that's what setuptools_scm does as its default... we could just as well do 0.0.1 or something, but I don't think the project is ready for 1.0.0 right off the bat. To me (and I think the material I've read on semantic versioning largely agrees), when you put out version 1.0.0 it means that the project has a stable API and usage instructions, whereas this is still kind of in flux; and 1.0.0 also implies having survived some degree of exposure to the real world (or at least it should). Such is my opinion anyway.
Thanks for taking this on BTW 😄
No problems, let's try for 0.1.0 then. :-)
And come to think of it... when it comes time to actually publish packages to PyPI I think it'd be useful to start with an alpha release - like, not just alpha development status, but an alpha version number, i.e. tag it with v0.1.0a0. That way we can check for any breakage in the release process before "using up" the precious v0.1.0 tag. Although that doesn't matter for updating the changelog.
Yep, because updating tags after the fact is a messy process.
That said, this being an alpha project, it's more or less acknowledged that there may be bugs that then need to be patched and new releases generated. Certainly once it's "stable", we'd be doing such release candidates to make sure the real release works as expected. :-)
Well, sure I agree to the extent that it will be understood that there may be significant bugs to fix and changes to make even when the version number doesn't have a prerelease (alpha or beta) component. (I know some projects keep an alpha or beta in their version number for many many releases to indicate that, like black did, but that messes up pip so I'm against it - I think the leading zero should be enough to convey non-stable status.)
I'm not so sure if it makes sense to make prereleases (alpha/beta/release candidate) regularly after the project becomes stable, i.e. hitting version 1.0. I don't think prereleases are as useful as they are for larger projects with lots of plugins or similar things that actively need testing. And we should be pretty confident in the release procedure at that point. I mean, we can certainly create prereleases when needed to test something out, I'm just questioning the value of making them a standard part of the process because 95% of the time the prerelease will be the same (commit) as the final release, and in the cases where it's not, it probably would have been fine to make a final release and a patch release with the fix.
But that's really not something we need to figure out now 😄