Discussion: Freeze Goatfile specification

[zekroTJA]

There are different strategies we can go for to ensure consistency and downwards compatibility of Goatfiles after release 1.0.0. Both suggestions are a trade-off between downwards compatibility and the flexibility to add new features and optionally alter the behavior of goat in the future.

Option A: Specification Freeze

Before release of v1.0.0, the Goatfile specification must be improved and reviewed so we are able to freeze the specification to allow full downwards compatibility after v1.0.0.

"Freeze" in this case means that all features currently available must be supported in feature 1.x versions, so that every previously created Goatfile can be executed resulting in the expected output. New features can be added as long as they do not break the expected behavior defined in the specification.

If breaking changes need to be introduced, this results in a major version bump (e.g. 2.x, 3.x …). This opens other discussion topics like how shall the support lifecycle look like for old major versions? Do we still maintain them alongside the latest major or simply deprecate them and focus on the latest major version?

Option B: Breaking Changes + Migrations

We could also go the way that we allow introduction of breaking changes within the same major version of Goat. This would require careful documentation of those breaking changes as well as providing migration tooling for existing Goatfiles. This allows more flexibility to add features and alter the behavior of the tool. On the other hand, this brings more complexity to releases and introduces more error sources (e.g. failing migrations, neglection of documentation, …).

[zekroTJA]

We decided on a trade-off solution between Option A and Option B.

Until release v1.0.0, we try to implement as most of the open feature issues that would break existing Goatfiles. After release v1.0.0, we will try to keep Goatfiles as consistent and downwards compatible as possible. But also, we don't want to block our paths to improve and add stuff by needing to find ugly and inconsistent workarounds just to keep compatibility.

Therefore, future releases will contain the ability to define Metadata in Goatfiles which allows version checks on them (see #44). Therefore, we can ensure that when breaking changes are introduced, you will have a better experience handling them.

Also, we will try to provide migration scripts you can use to get up to date quicker with large Goatfile code bases.