Create a layout stability policy

[eborden]

As proposed by @lspitzner, brittany needs a layout stability policy (cc @tfausak). Version 1.0.0.0 will introduce a milestone where stability is expected. This means that layout changes need to be minimized. Using versioning for this scheme is a likely strategy. Isolating layout change to major was the initially proposed scheme.

The PVP adds some complexity and a decision point with its two major components (MAJOR.MAJOR.MINOR). For this discussion we should refer to these as EPOCH.MAJOR.MINOR.POINT.

I propose the following system.

• Breaking layout changes should be isolated to EPOCH. A breaking layout change is an alteration to layout that is enabled by default.
• MAJOR should be used for breaking API changes in the brittany library that don't effect layout.
• MINOR can be used as expected via the PVP. Maintainers may introduce configurable layout changes that are "off by default" in MINOR versions.
• POINT can be used for bug fix releases.

Slightly more controversial, but should brittany maintain a list of "experimental" features that are exempt from the stability policy. This should allow experimentation without introducing restrictive versioning overhead. Should experimental features be kept behind a config flag?

[tfausak]

👍

Here are some examples of each level of breakage:

• EPOCH: #203 changed behavior by default and did not provide a way to opt out.
• MAJOR: (It was hard to find an example of this.) #50 would change the representation of some core data types.
• MINOR: #201 would add a new feature that would be opt-in.
• POINT: #234 was a bona fide bug fix. Yes it changes layout, but the previous output was not correct.

[scooby]

Should experimental features be kept behind a config flag?

Speaking as a user, I have a script that calls brittany via stack exec with a specified resolver. The potential impacts of an experimental feature and my immediate remedies / mitigations:

1. crashes or refuses to run: roll back to an older resolver
2. changes all the layout in a way I don't like: roll back to an older resolver
3. code loss: script refuses to run if git status reports unstaged files

On my end, then, there's little potential risk if you're pushing new features out aggressively.

[eborden]

Variations

conf_layout:
  lconfig_experimental: true

or

conf_layout:
  lconfig_unstable: true

[eborden]

:point_up: unnassigned since assignees will be used for active work.

[lspitzner]

I approve the proposed EPOCH.MAJOR.MINOR.POINT versioning scheme.

Even with what you mention, @scooby, I think this makes sense. We may have releases that add both a bugfix and that change layout. I.e. we don't want to force changes on the user just so they can get some bugfix.

This might involve just three actions:

1) For every change that involves different layout, add a config flag that toggles between old and new behaviour - this is the biggest item because all stuff needs to go behind a flag. 2) Keep track of two "default" configs: One that encodes "closest to previous behaviour" (baseline is first release of the epoch) and one that encodes our perceived "best default layout". 3) As suggested, add a flag that switches between the two things mentioned in 2)

Seems to be reasonable it its cost. And it does eliminate the cognitive overhead of weighing up which goal is more important in individual cases (better defaults vs stability). Which has been a minor factor already.