www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - Computing the next SemVer for dlang packages with dsemver

reply Robert burner Schadek <rburners gmail.com> writes:
https://code.dlang.org/packages/dsemver

is a program that computes the next SemVer for your dlang package.

It uses a slightly modified SemVer definition.

It does this by using the -X flag for dmd to get a json file of 
the symbols
and then compares them to the most recent git tag that resembles 
a SemVer.

First release is 1.0.0.
If a symbol is removed or its signature changed the major version 
is increment
and the minor and the bugfix number reset to 0.
If a new symbol is added, the minor number is incremented and the 
bug fix
number is set to 0.
If all symbol stay the same the bugfix number is incremented.

In an ideal world the dub registry would use this to compute the 
SemVer for you,
but baby steps.

I hope to see many bug reports and PRs.
Oct 21
next sibling parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 21.10.2020 um 16:47 schrieb Robert burner Schadek:
 https://code.dlang.org/packages/dsemver
 
 is a program that computes the next SemVer for your dlang package.
 
 It uses a slightly modified SemVer definition.
 
 It does this by using the -X flag for dmd to get a json file of the symbols
 and then compares them to the most recent git tag that resembles a SemVer.
 
 First release is 1.0.0.
 If a symbol is removed or its signature changed the major version is 
 increment
 and the minor and the bugfix number reset to 0.
 If a new symbol is added, the minor number is incremented and the bug fix
 number is set to 0.
 If all symbol stay the same the bugfix number is incremented.
 
 In an ideal world the dub registry would use this to compute the SemVer 
 for you,
 but baby steps.
 
 I hope to see many bug reports and PRs.
There are cases where a symbol change is not a breaking change in practice (maybe splitting up a function into two separate overloads) and where no symbol change is required to produce a real breaking change (e.g. a compile-time logic change within some template). In my experience it is often a judgement call where to draw the line, even sometimes deciding between a patch release and a major release. Of course, theoretically *any* change that is not backed by a preexisting specification is a breaking change in one way or another, especially when D's introspection or runtime behavior come into play... Anyway, I think this can be a very useful diagnostic tool to avoid accidental introduction of breaking changes at that level, and maybe also to actually generate new versions in certain contexts. However, I definitely don't see this as a potential feature of the registry in the sense that it automatically creates new versions for all packages.
Oct 21
next sibling parent reply Robert burner Schadek <rburners gmail.com> writes:
On Wednesday, 21 October 2020 at 15:27:46 UTC, Sönke Ludwig wrote:

 However, I definitely don't see this as a potential feature of 
 the registry in the sense that it automatically creates new 
 versions for all packages.
That is why I said in an ideal world and baby steps. Also, dsemver does not call git yet to create the new tag.
Oct 21
parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 21.10.2020 um 17:34 schrieb Robert burner Schadek:
 On Wednesday, 21 October 2020 at 15:27:46 UTC, Sönke Ludwig wrote:
 
 However, I definitely don't see this as a potential feature of the 
 registry in the sense that it automatically creates new versions for 
 all packages.
That is why I said in an ideal world and baby steps.
The thing is just that I don't think it is possible to find a set of rules that always work. There will always be something that should "obviously" be flagged as a breaking change and something that is extremely annoying to be detected as such (forcing a major version increment). But as some kind of warning/hint and with some kind of integration into the version tagging process (maybe forcing a manual version release on the registry after warnings come up) it could definitely be really nice.
 
 Also, dsemver does not call git yet to create the new tag.
Oct 21
parent Robert burner Schadek <rburners gmail.com> writes:
On Wednesday, 21 October 2020 at 17:58:53 UTC, Sönke Ludwig wrote:
 The thing is just that I don't think it is possible to find a 
 set of rules that always work. There will always be something 
 that should "obviously" be flagged as a breaking change and 
 something that is extremely annoying to be detected as such 
 (forcing a major version increment).
True, but if we can get 90% of the way there by a tool we would be a lot better of then where we are today. You should always be able to increment the SemVer by hand.
 But as some kind of warning/hint and with some kind of 
 integration into the version tagging process (maybe forcing a 
 manual version release on the registry after warnings come up) 
 it could definitely be really nice.
I'm thinking of a service that gives you a batch that shows you next SemVer of the master branch, as a start.
Oct 22
prev sibling parent Robert burner Schadek <rburners gmail.com> writes:
On Wednesday, 21 October 2020 at 15:27:46 UTC, Sönke Ludwig wrote:

To really get it correct properly most of dmd is needed anyway.
But this might a good first step to get out under the 0.x.x rug 
we are currently in
and a lot closer to actual meaning in the semver of a lib on 
code.dlang.org
Oct 21
prev sibling next sibling parent reply Guillaume Piolat <first.name gafam.com> writes:
On Wednesday, 21 October 2020 at 14:47:14 UTC, Robert burner 
Schadek wrote:
 Semantic versioning is useful, but 0.x.x versioning is a 
 pointless loophole. When a piece of D software is published, 
 and it is published if other people can find it on dub, it is 
 released. And released means 1.0.0 at least.
Agree. Or we won't ever have a dependable ecosystem. Please provide guarantees. Success of D is success of building upon the ecosystem of libraries. Something that people must consider to avoid too much major version tags is: - delay breaking changes and pack the breaking change at once - **have a small (and agreeable) public API surface**, use private and package identifier that are allowed to change spec - provide a changelog to go from a major to another major tag, no one want to read your git commits - a system of option using `version` identifier to make something similar to DMDFE's -preview. Configuration to gain compat at the expense of simplicity (option count can grow wildly).
Oct 21
parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 21.10.2020 um 17:41 schrieb Guillaume Piolat:
 On Wednesday, 21 October 2020 at 14:47:14 UTC, Robert burner Schadek wrote:
 Semantic versioning is useful, but 0.x.x versioning is a pointless 
 loophole. When a piece of D software is published, and it is published 
 if other people can find it on dub, it is released. And released means 
 1.0.0 at least.
Agree. Or we won't ever have a dependable ecosystem. Please provide guarantees. Success of D is success of building upon the ecosystem of libraries. Something that people must consider to avoid too much major version tags is: - delay breaking changes and pack the breaking change at once - **have a small (and agreeable) public API surface**, use private and package identifier that are allowed to change spec - provide a changelog to go from a major to another major tag, no one want to read your git commits - a system of option using `version` identifier to make something similar to DMDFE's -preview. Configuration to gain compat at the expense of simplicity (option count can grow wildly).
0.x.y vs. 1+.x.y is about the development process/state. Quite often a design is not yet fully fleshed out in the beginning and there are many incremental changes to the API. If 0.x.y didn't exist, that would simply mean that either the project gets more or less stuck with the initial (bad) design, or that it quickly increments major versions, effectively providing no more stability as in the 0.x.y case. But otherwise I agree, there are definitely quite a few projects that are beyond this stage and should make the jump to 1.0.0 (a few of mine included).
Oct 21
parent reply Robert burner Schadek <rburners gmail.com> writes:
On Wednesday, 21 October 2020 at 17:55:00 UTC, Sönke Ludwig wrote:

 0.x.y vs. 1+.x.y is about the development process/state. Quite 
 often a design is not yet fully fleshed out in the beginning 
 and there are many incremental changes to the API. If 0.x.y 
 didn't exist, that would simply mean that either the project 
 gets more or less stuck with the initial (bad) design, or that 
 it quickly increments major versions, effectively providing no 
 more stability as in the 0.x.y case.
I think that is the one mistake SemVer does. 0.x.y is just one big loophole. After the 1.x.y release an breaking api change requires a major version increment. The way it should be. Stability or unstable is only mentioned in the 0.x.y definitions. You are not stuck on a bad design, break the api, improve the api, increment the major version number. If you break the api in an 0.x.y version the hard part does not change. In both instances the users have to update their usage. In know in theory 0.x.y should be considered unstable. But by amount of 0.x.y we have you pretty much can't get anything done in D if you only use stable packages. The loophole has become the normal case. So what can we do, I see two major options: 1. we can live on the edge and use unstable packages and have no meaning in the SemVer number 2. we can acknowledge that most of them are stable, put a 1. in front and ignore the 0.x.y part of the SemVer definition and have the SemVer mean something dsemver does 2. And true there might be cases where dsemver does not increment the number correctly, but you can always increment by hand. Also if your api is not stable after your 1.x.y release and you break everything in 2.x.y, so what. Your users are also annoyed when you break your api from 0.1.x to 0.1.1. Only difference is they could have seen in coming by looking at the SemVer. I should stop ranting now.
Oct 22
next sibling parent Sebastiaan Koppe <mail skoppe.eu> writes:
On Thursday, 22 October 2020 at 08:59:18 UTC, Robert burner 
Schadek wrote:
 I should stop ranting now.
Not at all, I love it. Nice project.
Oct 22
prev sibling parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 22.10.2020 um 10:59 schrieb Robert burner Schadek:
 On Wednesday, 21 October 2020 at 17:55:00 UTC, Sönke Ludwig wrote:
 
 0.x.y vs. 1+.x.y is about the development process/state. Quite often a 
 design is not yet fully fleshed out in the beginning and there are 
 many incremental changes to the API. If 0.x.y didn't exist, that would 
 simply mean that either the project gets more or less stuck with the 
 initial (bad) design, or that it quickly increments major versions, 
 effectively providing no more stability as in the 0.x.y case.
I think that is the one mistake SemVer does. 0.x.y is just one big loophole. After the 1.x.y release an breaking api change requires a major version increment. The way it should be. Stability or unstable is only mentioned in the 0.x.y definitions. You are not stuck on a bad design, break the api, improve the api, increment the major version number. If you break the api in an 0.x.y version the hard part does not change. In both instances the users have to update their usage. In know in theory 0.x.y should be considered unstable. But by amount of 0.x.y we have you pretty much can't get anything done in D if you only use stable packages. The loophole has become the normal case. So what can we do, I see two major options: 1. we can live on the edge and use unstable packages and have no meaning in the    SemVer number 2. we can acknowledge that most of them are stable, put a 1. in front and ignore    the 0.x.y part of the SemVer definition and have the SemVer mean something dsemver does 2. And true there might be cases where dsemver does not increment the number correctly, but you can always increment by hand. Also if your api is not stable after your 1.x.y release and you break everything in 2.x.y, so what. Your users are also annoyed when you break your api from 0.1.x to 0.1.1. Only difference is they could have seen in coming by looking at the SemVer. I should stop ranting now.
The real alternative to 0.x.y is 1.0.0-alpha.1+, though, with the drawback that there is no supported means to still provide something like a distinction between breaking (x) and non-breaking (y) changes. There is also value in having some kind of indicator that the code has reached a certain level of maturity (1.0.0).
Oct 22
parent =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 22.10.2020 um 17:50 schrieb Sönke Ludwig:
 with the drawback that there is no supported means to still provide 
 something like a distinction between breaking (x) and non-breaking (y) 
 changes.
* with supported I mean that you can use `~>0.x.y` to restrict to a certain x, which would be less obvious for something like 1.0.0-alpha.x.y.
Oct 22
prev sibling parent James Blachly <james.blachly gmail.com> writes:
On 10/21/20 10:47 AM, Robert burner Schadek wrote:
 https://code.dlang.org/packages/dsemver
 
 is a program that computes the next SemVer for your dlang package.
 
As indicated downthread, this could be a great ecosystem partner with dmd-as-a-library. Thank you Robert!
Oct 23