Demo: merge authoring

[ddbeck]

This PR demonstrates one way to author merges, as part of the aspects project work. It assumes compatibility with #4034 and #4079; if you haven't seen those, you should review them first!

Because this PR is partly based on #4079, reviewing 075fac9 shows the actual authoring differences. I'll rebase this PR as soon as the other one merges.

Synopsis

Merges are declared by adding kind: merged and redirect_target: <target-feature-id> to a feature description. That's the authoring change.

As a convenience to authors, we'll add (generated) comments to the merge targets, to note when other features have been merged into it.

Merged features' BCD keys are implicitly shared into the target feature; you can see the result of this in the .dist file. The "promotion" of keys into merge targets will be subject to some guidelines and automatic enforcement, the most important of which is that you can't merge a feature with a lower status into a feature with a higher status.

Feedback I'm looking for

• Does this authoring communicate a relationship between two features, the merged and merge target?
• Does this authoring look familiar or new, clear or ambiguous?
• Can you imagine yourself writing this or using a tool to generate it? If not, what would you imagine writing?

What about….?

• Baseline dates. In this regime, Baseline dates don't change upon merging. A feature's "birth date" holds steady, even if other features merge into it. The use of compat sets means that we have the possibility of changing this behavior in the future (e.g., to generate a rolling Baseline date and a historic inception date), but until we have an actual consumer for such data, I am not planning to implement it.

• Merge metadata. We might want additional information about the merge, such as a reason or merge date. I'm not rejecting them, but the authoring story for such data is not new and interesting (compare with discouraged features), so I didn't think it would be very helpful to demonstrate them here.

• Merging this feature, specifically. I pulled an example from our open issues (specifically, Merge grid-animation into grid once it becomes Baseline Widely Available #2441). Is this a good idea, specifically? I think this is an easy case, but this is a demo of authoring only—I do not intend to merge this PR. We might ultimately adopt merge guidelines that prevent merging grid-animation (e.g., we might wish to wait some longer interval before merging the feature or to consult with consumers ahead of merging). But it will be easier to demo possible enforcement and guidelines with some of our more complicated cases after we have a notation for feature merging.

• Alternatives. I tried out other authoring formats, such as inverting merges (e.g., adding a subsumed array to the merge target and using convenience comments on the merged features). This was more cumbersome to write and hid the main consequence of merging a feature: changing a feature's kind from the default implicit "feature" value.

[ddbeck]

Because this PR is partly based on #4079, reviewing 075fac9 shows the actual authoring differences. You might want to review that commit instead.

[captainbrosset]

Does the dist file for a merged feature stay the same?
I'm thinking that having a generated comment in the dist file along the lines of "Keys moved to merge target grid.yml.dist" would be helpful.
Depending on what I'm doing, I'm looking at the yml file, or the dist file, but not always at both. If the info is in both, it makes my life a little easier.

[captainbrosset]

Would this need to be added manually? If so, there's always a risk of forgetting about it.

Not sure what else we can do though. Maybe drop it? I know I just said having this kind of info in both yml and dist was useful. I guess I'm disagreeing with myself here.

[captainbrosset]

I suggest prefixing this comment with something like:
# These keys come from grid-animations which merges into great
(or something much better).

Reviewing dist files is very useful and frequent. The more info we have about each key, the better.

[captainbrosset]

• Does this authoring communicate a relationship between two features, the merged and merge target?

Yes, I like that you're reusing the kind field here. The only I'd add is comments in the source and target dist files to help maintainers quickly see that a set of keys have either moved somewhere else, or been added from another feature.

• Does this authoring look familiar or new, clear or ambiguous?

It looks pretty straightforward to me.

• Can you imagine yourself writing this or using a tool to generate it? If not, what would you imagine writing?

I can imagine myself write this.

• Baseline dates. In this regime, Baseline dates don't change upon merging. A feature's "birth date" holds steady, even if other features merge into it. The use of compat sets means that we have the possibility of changing this behavior in the future (e.g., to generate a rolling Baseline date and a historic inception date), but until we have an actual consumer for such data, I am not planning to implement it.

I agree with starting this way. As we turn our attention to other examples of merges, we might be tempted to change the Baseline date. At that point, we can discuss again.
The typical use case for this is merging 2 very old features that are both Widely Available. Basically, things for which we don't care about dates anymore.
Do you think there are cases where we'd want to use this sooner? We might want to enforce (probably by code) the fact that we can't merge a feature that's at least Widely Available + X months (X to be defined).

• Merge metadata. We might want additional information about the merge, such as a reason or merge date. I'm not rejecting them, but the authoring story for such data is not new and interesting (compare with discouraged features), so I didn't think it would be very helpful to demonstrate them here.

Again, the typical use case in my mind is almost automatic, and therefore boring: feature A became Baseline 10 years ago, feature B built on top of it and became Baseline 5 years ago, now we merge them just based on time.
If that's, indeed, the typical use case, I don't think a comment is really needed.

• Merging this feature, specifically. I pulled an example from our open issues (specifically, Merge grid-animation into grid once it becomes Baseline Widely Available #2441). Is this a good idea, specifically? I think this is an easy case, but this is a demo of authoring only—I do not intend to merge this PR. We might ultimately adopt merge guidelines that prevent merging grid-animation (e.g., we might wish to wait some longer interval before merging the feature or to consult with consumers ahead of merging). But it will be easier to demo possible enforcement and guidelines with some of our more complicated cases after we have a notation for feature merging.

I don't know how to reason about this. How long is long enough? My feeling is, it's probably fine. I don't hear developers talk about grid animation as a separate feature anymore. But we should find something more scientific.

This does trigger a thought though: should we have a process in place for also updating descriptions when we merge? In this particular case, I don't think we'd want to do it. But I can see there being cases where the scope of the target feature is expanded in a way that we want to kind of merge the 2 descriptions (source and target).

• Alternatives. I tried out other authoring formats, such as inverting merges (e.g., adding a subsumed array to the merge target and using convenience comments on the merged features). This was more cumbersome to write and hid the main consequence of merging a feature: changing a feature's kind from the default implicit "feature" value.

I really like using kind.