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.

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.

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.

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).

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

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).

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.

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.

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.

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.