Breakage Policy

[zeylahellyer]

Copied from PR #1106, which wants to add a semantic versioning policy:

Library functionality unrelated to the Discord API is subject to standard Semantic Versioning rules. However, any functionality that relies on the Discord API may break in a minor release if it can not be avoided.

This was written for both the http and model crates. I will be posting my own thoughts in a separate reply tonight.

[AEnterprise]

I think we should be doing a major version increase a change that causes code to no longer compile is done.

This is exactly what semver is for, this might mean more regular major releases but i do not see any downsides to doing this. while i only see downsides to sidestepping semver like this. It will make people paranoid and annoyed because yet again twilight pushed a minor update and now your code doesn't compile, yet again.

[vilgotf]

(My understanding): Discord bumps its API version on major changes but not on some tricky (in Rust) changes like new struct fields (model), or when something turns optional (http/model).

model is mostly fixed by adding #[non_exhaustive] to most public structs. This allows adding new fields in a backwards compatible way, but disallows constructing structs outside of twilight (without the help of builders). #[non_exhaustive] is not a big downside since very few structs are supposed to be constructed, so it's possible to provide builders for all of them. Adding & renaming fields would thus be supported (removals are already supported with deprecations).

When a field becomes optional is more tricky. We can either add a new field with the option and deprecate the old field or treat default values ("" for string or 0 for integers) as None.

Twilight could be forced to produce incorrect requests until users fix their code (with deprecation warning hints) which is fine as it would not break semver. We'd of course try to avoid this, but it would be better than breaking semver.