Enhancement: Implement semantic versioning
edwinsage opened this issue · 4 comments
MC has been updated and extended in a variety of ways, but the versioning used does not communicate what version one might need in any consistent way. Since MC is intended to frequently be used from scripts or other software, it's important to know when things change. Moving forward, I'd like to see reasonable adherence to semantic versioning (https://semver.org/).
For the purposes of MC, I would consider it important to increment the major number any time:
- handling of existing command line arguments is changed (including ones added since the last major release)
- existing output formats are modified (e.g. changes are made to how multiline messages are printed to STDOUT)
Changing these things can break an existing script that uses MC, and that should be apparent just by the version number. It can feel a little weird to increase the major version number when all you did was tweaked the way you indent JSON output or something, but from the perspective of someone writing code that relies on knowing the behavior of MC, it's pretty important.
That makes sense. I will try to get better at this.
Just to be clear:
If there is change in the output (stdout), e.g. new space while reporting a room id, then use a new major version number.
If there is a change in the debugging info (stderr), e.g. the text of debug, info, warning, or error changes, then do NOT use a new major version number.
Do I see this correctly?
I would say that is reasonable. If you want to be formal, it's up to you to declare what you say is included in the "public API", and update major version number whenever details of anything in that change, but I think it's reasonable to treat it as standard inputs and outputs that you would expect another program or script which calls MC to make use of.
If error output is important for programs but you expect the details to change a lot, you could make the basic error types an API thing (e.g. error output uses prefixes such as "WARNING" or "FATAL") which are clearly defined as part of an API, but state that the exact text that follows is subject to change.
If error output is important for programs but you expect the details to change a lot, you could make the basic error types an API thing (e.g. error output uses prefixes such as "WARNING" or "FATAL") which are clearly defined as part of an API, but state that the exact text that follows is subject to change.
That is pretty much as I treat it: there is the logging pattern "date", "module", "ERROR: ", and then some "description", where the description could change without notice. I.e. description change will NOT create a new MAJOR version.