Swift Evolution Metadata Transition (Completed)

Swift Website
1

The Swift Evolution Dashboard is driven by a JSON file of proposal metadata. In addition, a number of other projects in the Swift community are clients of this file.

A review of proposed metadata schema changes and a transition plan to minimize disruption for clients ran from March 19 - April, 19, 2024.

Reviewers provided feedback which led to a number of changes and refinements to the proposal.

The transition period to migrate to the new schema begins today and runs until July 22. 2024.

Thank you to everyone who participated in the review!

Transition Summary

Full details of all schema changes are available in the initial post of Swift Evolution Metadata Proposed Changes.

The transition period to the new schema begins today and runs until July 22, 2024.

During the transition period:

  • The existing metadata file will continue to be available at:
    https://download.swift.org/swift-evolution/proposals.json

  • The new metadata file is now available at:
    https://download.swift.org/swift-evolution/v1/evolution.json

  • Both files include all of the newly added proposal fields

  • Both files still include fields that will be removed at the end of the transition period

  • The schema version has a major version of '0' beginning with '0.1.0'

Transition Completion

At the end of the transition period:

  • The legacy proposals.json metadata file will be replaced with a permanent file that includes a message and the URL of the new metadata file

  • Fields that are no longer be part of the schema will be removed

  • The schema version will reach 1.0.0

Transition Notes

These notes describe the actions required to migrate to the new schema to avoid breaking.

The following sections can be done in any order.

Migrate to the evolution.json file

To begin using the evolution.json file:

  1. Decode the top-level object in the new file format

    To quickly bootstrap you could use a small Codable struct that initially ignores all top-level properties except proposals:

    struct Evolution: Codable {
  // Array of existing Codable type used for `proposals.json`
  let proposals: [Proposal] 
}

  2. Access the array of proposal metadata using the proposals property in the top-level object. This is meant to be a drop-in replacement for the existing array of proposal metadata.

  3. Update from status state values with a leading dot (e.g. “.implemented”) to values without a leading dot (e.g. “implemented”).

    :warning: This seemingly small change will probably cause the most code changes

Migrate from reviewManager to the reviewManagers array

  1. Update to use the reviewManagers array.
    Existing code the handles the authors array can likely be used as a starting point.

  2. Remove any dependencies on the reviewManager property.
    The reviewManager property will be removed at the end of the transition period.

Eliminate dependencies on removed fields

Your code may or may not depend on these fields depending on how completely it decodes the existing proposals.json file.

In most cases, eliminating dependencies will simply mean no longer decoding these fields.

In addition to the reviewManager field, the following fields will be removed at the end of the transition period:

Warnings and Errors

  • stage

Tracking bugs

  • assignee
  • radar
  • resolution
  • status
  • title

New Property Notes

Warnings and Errors

Initially the new code and suggestion properties will always have the value of zero and an empty string, respectively. A follow-on task to the metadata changes will be to rationalize the existing set of warnings and errors and make the results public. The new properties will be given valid values as part of that effort.

Upcoming Feature Flag

The values of the upcomingFeatureFlag property accurately reflect the current state of proposals.

However, there are a number of swift-evolution PRs to add the additional annotations that indicate the language mode when the flag is always enabled and in at least one case, when the flag is available.

While in this state of flux, the enabledInLanguageMode field will not be accurate.

SE-0337, SE-0414, Multiple

Discussions

The discussions property includes discussion metadata from the Review header field. It also extracts from the Decision Notes header field, as that has been used as an alternate naming in many proposals.

Many proposals do not follow the proposal template guidelines for a well-formed Review field. For those proposals, no discussions are extracted. Corrections for those proposals will be submitted as PRs to swift-evolution.

A PR has already been merged to update existing discussions to be listed in chronological order. Correct the chronological order of proposal review discussions by dempseyatgithub · Pull Request #2402 · swiftlang/swift-evolution · GitHub

Conclusion

Once again, thank you to everyone who participated in the review!

Please use this thread to post any questions or comments regarding the transition to the new schema. Remember that the full listing and description of changes is available at Swift Evolution Metadata Proposed Changes.

7 Likes
2

I created a small JSON file that removes all properties that will be removed at the end of the metadata transition.

I've been using it to verify that the SE Dashboard script no longer depends on the removed properties and thought it might be useful to others.

The test file contains only five proposals, but there is at least one example of each of the removals.

As a bonus, it contains at least one example of each of the newly added properties.

3 Likes
3

TRANSITION UPDATE: Upcoming Feature Flag fields

The new Swift evolution metadata schema includes three new properties as part of the upcoming feature flag object:

  • flag
  • available
  • alwaysEnabledInLanguageMode

The available and alwaysEnabledInLanguageMode are optional and are extracted from annotations in the Upcoming Feature Flag header field in an evolution proposal.

To date, however, after over three months, the PRs to add the annotations have not been accepted in the swift-evolution repository. (SE-0337, SE-0414, Multiple)

My plan is to reconnect with the language steering group to confirm and possibly revisit the terminology used in these annotations.

For the moment, I am proposing and planning on dropping the available and alwaysEnabledInLanguageMode fields from version 1.0 of the schema.

This is for the following reasons:

  • Until the PRs land, those two properties do not provide accurate information so they are misleading and of limited value
  • The terminology may change and it is desirable for the metadata property names to match if possible
  • Adding properties to the metadata is not a breaking change but renaming properties is, so removing them for the moment and adding them later causes less disruption
  • Both properties are optional, so removing them will not break any clients that have migrated. Those properties will just never appear.

The intent is to add back the two properties once the proposals have the correct annotations.

Any feedback on this is welcome.

UPDATE July 12, 2024: This change is now in effect

7 Likes
4

The transition period has now ended with the following changes:

  • The legacy proposals.json metadata file has been replaced with a permanent file that includes a message and the URL of the new metadata file

  • Properties that are no longer part of the schema have been removed

  • The schema version is now 1.0.0

Thank you again to everyone who provided feedback on the updated schema.

4 Likes