Create a layout stability policy #235

New Issue

2019-06-17T22:30:26+02:00

eborden commented

2019-06-17 22:30:26 +02:00

(Migrated from github.com)

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?

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 commented

2019-06-18 02:15:54 +02:00

(Migrated from github.com)

👍

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.

👍 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 commented

2019-06-18 04:08:08 +02:00

(Migrated from github.com)

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:

crashes or refuses to run: roll back to an older resolver
changes all the layout in a way I don't like: roll back to an older resolver
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.

_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 commented

2019-06-18 05:58:30 +02:00

(Migrated from github.com)

Variations

conf_layout:
  lconfig_experimental: true

or

conf_layout:
  lconfig_unstable: true

Variations ```yaml conf_layout: lconfig_experimental: true ``` or ```yaml conf_layout: lconfig_unstable: true ```

eborden commented

2019-06-19 17:10:56 +02:00

(Migrated from github.com)

☝️ unnassigned since assignees will be used for active work.

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

lspitzner commented

2019-06-24 09:17:16 +02:00

(Migrated from github.com)

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:

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.
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".
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.

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.

Sign in to join this conversation.

No Milestone

No project

No Assignees

1 Participants

Notifications

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: hexagoxel/brittany#235