Swift Evolution Metadata Proposed Changes

[James_Dempsey]

@Victor_Martins

I propose we add the following fields to each proposal:

{
  "id": String,
  "title": String,
  ...
  "previousProposalIDs": [String]?,
  "discussions": [ // A list of the related discussions in chronological order
    {
      "title": String, // "Pitch", "Review", "Acceptance", ...
      "link": String
    }
  ]
}

I think these would be useful additions. For example, I have been thinking it might be a good addition to the dashboard to link directly to the review thread for proposals in active review.

I also think these are good as originally pitched in terms of naming / structure / types.

Additional feedback from others is welcome.

Some thoughts:

previousProposalIDs

• This is not used often, so I agree it should be an optional value, similar to implementation and trackingBugs.

• In the original header field, the value contains relative links to the previous proposals. I agree that only the proposal ID is necessary, since the full information about the previous proposal is present in that proposal's metadata. (Side note: The proposal template says the link text should include more info about the relationship such as "Extracted from SE-XXXX", but none of the existing proposals with this header field follow this guideline.)

• Although the original header field is named "Previous Proposal", I agree that since the metadata only includes IDs that previousProposalIDs is a better name.

• I think including only the previous proposals is preferable to 'related proposals' which could include both previous and follow-on proposals. This makes the relationship clear and it isn't too onerous to derive the inverse relationship for clients who wish to do so.

discussions

• All proposals should have links to discussion threads so a non-optional array makes sense.

• The original header field is labeled "Review". I think it is a good rule of thumb to prefer the naming used in the proposal, barring a good reason.

  In this case, I think discussions is much more clear in describing what the values are. Even the proposal template for the "Review" field defines it as: "a history of all discussion threads about this proposal".

• Although the header field is supposed to list these in chronological order, some proposals currently list them in reverse chronological order. I believe the metadata field should be in the same order as in the proposal and that the proposals should be updated via PR.

  (In general, I don't think the metadata extraction should be performing additional processing to fix errors in proposals. The proposals should be updated.)

• I could see title or name being used for each discussion, but I am fine with title.