Swift Evolution Metadata Transition

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 · apple/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

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