Fix versioning

[jbdyn]

In this early stage, the project should do releases with date versioning as the code base is quite unstable.

When the project is mature enough, semantic versioning might be used instead.

TL;DR: Use the versioning scheme MAJOR.MINOR based on git tags. See below for details.

• implement setuptools_scm
• tag versions for proper indexing
• create changelogs for each version
• release latest version
• setup workflow for release (draft) creation
• inform about versioning in README.md

[jbdyn]

After discussion with @otizonaizit, we agreed on a MAJOR.MINOR versioning scheme as a compromise between semantic and calendar versioning.

Reasoning

• Semantic versioning suggests promises about (non-)breaking changes which are hard to keep, thus every bump is considered potentially breaking.
• Calendar versioning does not transport any sense of project progress.

Handling

• MAJOR bumps occur on code base rewrites, except for 0 -> 1, which indicates a switch from test stage to production stage.
• Every other commit on main is a MINOR change.

[otizonaizit]

hmm, not sure about this point:

* find a way to automatically bump the version upon commit in `main`

why would you want to automatically bump the version number? I mean, each commit has its own SHA, so it is identifiable. The version number should be bumped on release only, which is probably not happening at every push to main?

[jbdyn]

[...], which is probably not happening at every push to main?

I actually thought so. main is also protected right now, so every commit in there is a merge commit. Intuitively, I would have published a release right away every time.

[otizonaizit]

[...], which is probably not happening at every push to main?

I actually thought so. main is also protected right now, so every commit in there is a merge commit. Intuitively, I would have published a release right away every time.

Which means you will have a new release for the contributed fix of a typo in the docs? With push to PyPI? I don't know, but it seems a bit excessive to me. And it makes it impossible to publish alpha or beta releases... To me a release is a message to the world saying: look, we have done something new, fixed some things, improved the speed, whatever. So a release comes with release notes explaining what has been done, highlighting backward incompatible changes and what not. If you release at every merge, what would be the release notes? The message of the merge commit? But that could contain internal details that the users do not need to care about. And it becomes unclear which release is relevant and which is not.

Before installing a new version of something I tend to read the release notes so that I can make an informed decision. If there are ten releases a month, with irrelevant release notes, then it is the same as asking to people to just track main and shut up ;-)

[otizonaizit]

Another situation where automatic release on push to main could be problematic:

Imagine you are doing a big refactoring, where you introduce a new object hierarchy.

This would ideally be done in a series of PRs, where the first one introduces the new objects, the second one migrates part of the code to use the new objects, the third one takes care of backward compatibility and so on and so forth. It is important to split this work in several PRs, because you do not want the refactoring to be a one-shot thing. You may merge the first PR and then wait a bit while you finish the second. You may want to revert the third PR but leave the first two in place.

So, while main remains runnable at all times, it is not supposed to be consumed by anyone expect developers and contributors. When the refactoring is completed, a new release is done and end-users are supposed to upgrade to use the new shiny interface.

[jbdyn]

Okay, I see that a release on every commit in main will be too noisy for the user.

So instead, I suggest to base the project's version entirely on git tags, meaning to also use setuptools_scm. Pushing a new tag could then result in a triggered pipeline, generating a release draft.

[otizonaizit]

So instead, I suggest to base the project's version entirely on git tags, meaning to also use setuptools_scm. Pushing a new tag could then result in a triggered pipeline, generating a release draft.

Yes, that is a very good idea, I think GitHub picks up annotated tags automatically as releases and it uses the tag note as release notes

[jbdyn]

That sounds nice! Do I need to configure the repo for this?
I cannot find such a mechanism in the docs.

[otizonaizit]

That sounds nice! Do I need to configure the repo for this?
I cannot find such a mechanism in the docs.

https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes

[otizonaizit]

That sounds nice! Do I need to configure the repo for this?
I cannot find such a mechanism in the docs.

https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes

Actually that link is not exactly the thing I was talking about. I need to dig deeper.

[jbdyn]

As far as I can tell, people use diverse GitHub Actions for this.

[otizonaizit]

As far as I can tell, people use diverse GitHub Actions for this.

This is the manual way to do it:
https://cli.github.com/manual/gh_release_create

[jbdyn]

I am tending towards this recipe:

1. Merge PR via GitHub's web UI.
2. Create a changelog draft with something like cliff AND edit it by hand.
3. Commit and tag with the new version (and an appropriate message).
4. Push.
5. Trigger the CI
   • building the package,
   • uploading it to PyPI,
   • building and updating the website with documentation and
   • creating a new release on GitHub.

I like the reasoning by the Keep a Changelog project and see why ELVA would benefit from manual releases and notes.
What I also like is its suggestion for commit grouping, which can be automated without adding annoying prefixes like feat(object): foo or similar.

The CI is hosted and maintained by us. I don't want to rely on GitHub Actions for this as we might switch the host at some point.