Versioning policy?

[mvz]

It seems we are sort of trying to follow semantic versioning with Reek. I'd like to discuss what we consider breaking and non-breaking changes. We should probably touch upon the following aspects, at least:

• The CLI interface. I would say adding options is a non-breaking change, and would warrant an update of the minor version. Removing options is a breaking change and requires a major version update (we did this going to reek 2). Adding a report format probably also warrents a minor version upgrade, which means we should release 2.1 next.
• The API. We haven't really defined a 'public' API for using Reek programmatically, and we've only just started testing it (in #417). So, this is basically a blank slate at the moment.
• List of detected smells. We could say adding a smell warrants a minor release, removing a smell is a breaking change. This makes sense if you consider that the CLI allows running a single smell detector.
• Consistency of detected smells. This is very hard to guarantee. If we fix a bug in one of the detectors, some fragrant code may become smelly, or vice versa. I don't think we should bother with this.
• Smell configuration. The detectors are quite tolerant regarding configuration options that they don't recognize, so I would regard any change here as only requiring a minor release.

[mvz]

In fact, we should have released 2.1 instead of 2.0.2 because we added the JSON format.

[chastell]

I agree with all of the above.

• The API: I think shaping what is and what is not part of the ‘public API’ is a good goal for reek 3.0, and up until 3.0 I wouldn’t consider API changes to be breaking.
• Consistency of detected smells: in most cases definitely not breaking; the only breaking ones would probably fall under ‘bugs in how reek works’ or ‘not (really) detecting a smell anymore’ anyway.
• Smell configuration: this is the most fuzzy one; I would go with ‘any change here as only requiring a minor release’ for now and see how it goes, maybe revisit this in reek 3.0+.

[troessner]

The CLI interface. I would say adding options is a non-breaking change, and would warrant an update of the minor version. Removing options is a breaking change and requires a major version update (we did this going to reek 2). Adding a report format probably also warrents a minor version upgrade, which means we should release 2.1 next. The API. We haven't really defined a 'public' API for using Reek programmatically, and we've only just started testing it (in #417). So, this is basically a blank slate at the moment. List of detected smells. We could say adding a smell warrants a minor release, removing a smell is a breaking change. This makes sense if you consider that the CLI allows running a single smell detector. Consistency of detected smells. This is very hard to guarantee. If we fix a bug in one of the detectors, some fragrant code may become smelly, or vice versa. I don't think we should bother with this. Smell configuration. The detectors are quite tolerant regarding configuration options that they don't recognize, so I would regard any change here as only requiring a minor release.

I agree with all-the-things, very good, comprehensive list.

The API: I think shaping what is and what is not part of the ‘public API’ is a good goal for reek 3.0, and up until 3.0 I wouldn’t consider API changes to be breaking.

Makes sense to me as well, I just updated our reek-3 issue with this: #401

[troessner]

Adapted @mvz suggestion from above and put it into /docs in #509 - closing this one once that is merged.

[mvz]

Fixed in #509.