Respecting semantic release versioning conventions

[smoia]

This discussion is related to the adoption of auto for automatic releases (PR #181 )

While @hipstersmoothie was explaining in the issue intuit/auto#1080 how to use auto for beta releases, I realised that we're not respecting semantic versioning conventions (as explained here ).

In practice, thinking that our project is still in beta stage, our latest version should be 0.0.0-beta.6 instead of 1.3.0-beta, with next release planned being 0.0.0-beta.7 rather than 2.0.0-beta.

If I had to decide whether I wanted people to know that we're in beta stage or that we made a huge change to the repository to the point that the behaviour of the package is very different from the package we had in November, I'd rather go for the second option, and either keep being non-respectful of semantic versioning convention or drop the "beta" suffix.
This mainly comes from the idea that, in an academic open development context (where most of the packages are never reaching release 1.0.0 due to the idea that the package is never stable or finished enough), it would be more important to say in the most direct way "hey, here something really changed and you should consider updating" .

However, I also see why it would be more correct to state we're at version 0.0.0-beta.7 rather than 2.0.0 - after all, we are in a pre-production stage, and (my fault, apologies) not respecting the convention we should be using to communicate the development stage

I would like to hear your thoughts @vinferrer @rmarkello @RayStick @eurunuela (and all the other devs) about this. I actually would like to hear what other people that have been in this context more than us think about it (for instance, @KirstieJane @yarikoptic @oesteban @emdupre what did you do with your projects?).

Proposed solutions

Knowing that ideally we want people to know when we're doing major changes and at the same time that we're still in development stage:

• if we decide to drop the beta suffix, we could still specify it's a project in development here in GitHub, in our documentation, and in Pipy (our package is marked as beta release stage)
• if we decide to adhere more strictly to semantic versioning, the main way to show breaking changes could be the changelog - that should be better maintained with auto.
• feel free to offer other solutions.

Outstanding questions

• Do we want to strictly respect semantic versioning? Do we want to respect it at all?
• Should our next release be 2.0.0 or 0.0.0-beta.7?
• Do you have any other option, keeping in mind that we want people to know when we're doing major changes and at the same time that we're still in development stage?

[hipstersmoothie]

When in 0.x in semver it communicates that the package is still in the beta stage. https://semver.org/#spec-item-4

I use a special label to communicate this so consumers can still know that there was a breaking change.

https://mobile.twitter.com/HipsterSmoothie/status/1223054336625795074

[smoia]

@hipstersmoothie, that's a very good point, and I'm so ashamed I totally missed it!
The question then becomes:
What should we do? Move out of beta stage already (we're not that far), or change our semantic versioning and correct it?

[eurunuela]

I'm all for changing our semantic versioning and correcting. I've always thought that betas should stay below v1.

[oesteban]

Sorry to join late to the party. Besides the use of <0.x for betas, this is what we have ended up doing in fMRIPrep - https://www.nipreps.org/devs/releases/

[smoia]

Hi @oesteban ! No worries, better late than never! Glad you joined the party.

Calendar versioning is actually an interesting approach that we could take into account for our development! If I'm not wrong, AFNI follows the same scheme, right?
@physiopy/all what do you think about it?

[eurunuela]

I'm not a fan of calendar versioning myself. People usually associate the version number to how advanced the development is. So, it can give the impression of phys2bids being super developed and that's not the case.

As I previously said, and as Óscar mentioned, I'd use anything below 1.0.0 for betas.

[oesteban]

We found that semantic versioning had too much granularity for us. In the end, with the software progressing fast, it was easier to define clear rules of when the patch version would change and push a new minor for everything else.

Finally the year at the front gives us a very clear idea of how old is the version of the user.

[eurunuela]

I totally get it and understand the reasons behind that decision. My concern is I am not sure we're developing fast enough for such a versioning approach.

[yarikoptic]

oh, I never commented on, sorry.

semver is applicable regardless of the speed of development IMHO... anyways - I see now all wonderful v2.1.. tags, so the right decision was made IMHO minor tuneup(s) are due: #311