0.3.2 contains a breaking change (new parameter to `lex`)

[epage]

Noticed this when dependabot tried to upgrade my survey of markdown parsers: rosetta-rs/md-rosetta-rs#14

[darakian]

That makes sense. The 0.3.x releases will have a lot of breaking changes as the library works toward common mark compliance.

[epage]

Rust crates are generally expected to follow cargo's variant of the semver spec in which 0.3.x releases must be backwards compatible with each other. Deviating from this is disruptive to users and erodes their trust in using your crate in the future.

[darakian]

This is a pre 1.0.0 library and is considered unstable for the time being. I am making no promises of backwards compatibility for the time being and if you read the status section of my readme file you'll see a line stating

All output is considered unstable for the time being.

Perhaps I could be more clear that interfaces are also considered unstable. Let me know if that would be useful.

Deviating from this is disruptive to users and erodes their trust in using your crate in the future.

You're welcome to use other software 👍

[epage]

This is a pre 1.0.0 library and is considered unstable for the time being. I

Even pre-1.0.0 libraries generally have expectations on them in the Rust ecosystem like following semver.

All output is considered unstable for the time being.

Yes, you would need to specify also the API, that you are not following semver (according to cargo).

The thing that isn't clear to me is what is the value of publishing if this isn't being setup for people to use by following semver.

[darakian]

I've updated the readme to indicate that interfaces are also considered unstable. For your own edification the current semver spec defines 0.x.y as development https://semver.org/#spec-item-4

[epage]

From https://semver.org/#spec-item-4

Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Yes, the semver spec says that which is why I've been specifically calling out cargo's variant of semver

From https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility

Versions are considered compatible if their left-most non-zero major/minor/patch component is the same. For example, 1.0.3 and 1.1.0 are considered compatible, and thus it should be safe to update from the older release to the newer one. However, an update from 1.1.0 to 2.0.0 would not be allowed to be made automatically. This convention also applies to versions with leading zeros. For example, 0.1.0 and 0.1.2 are compatible, but 0.1.0 and 0.2.0 are not. Similarly, 0.0.1 and 0.0.2 are not compatible.

[darakian]

is there anything else I can do for you beyond updating the readme?

[epage]

The statement is still unclear

All output and interfaces are considered unstable for the time being.

Generally, people will refer to pre-1.0 crates as unstable. A more clear "this project is not following semver, use = version requirements when depending on it" would be needed.

[darakian]

Generally, people will refer to pre-1.0 crates as unstable.

That was my thinking as well.

[epage]

That wasn't quite what I meant. The refer to pre-1.0 crates as "unstable" despite expecting no breaking changes between patch releases. The term "unstable" is very context-dependent on how people will read into it, so in the context it is being used people will not get the intended meaning from it.

[darakian]

I follow the semver.org thinking on my pre 1.0.0 releases; anything can change at anytime. For my project the 0.3.x releases will be used as steps toward common mark compliance. If that's not useful to you then you're welcome to pin a version or to use a different piece of software.