Document our WoW on milestones for the protocol

[e-backmark-ericsson]

Description

Today we have an ad hoc way of working when it comes to milestone handling in the Eiffel protocol repository, where the milestones for each upcoming edition is filled with issues intended for that edition or already merged on to master and thus will be part of the edition.

Motivation

It's better to have processes described in text than having them ad hoc :)

Exemplification

See #277 (comment)

Benefits

Less risk of missing creating milestones and updating them

Possible Drawbacks

None

[m-linner-ericsson]

👍

Who has the most experience with this? Could those persons get started on a PR and the rest of us add in?

[m-linner-ericsson]

When implementing this please add a description of how to update the meta-object. Maybe something like this:

1. Any change to meta requires all events to be updated.
2. Any schema of a specific version of an event must also include a version-specific reference to the meta-object

[magnusbaeck]

Any schema of a specific version of an event must also include the linked meta object of a specific version

I don't think I understand this one. Could you please elaborate?

[m-linner-ericsson]

@magnusbaeck Edited my comment with the aim to make it more understandable.

[e-backmark-ericsson]

Since the idea to break out meta in the JSON schemas is discontinued, the comment from @m-linner-ericsson on Dec 15 above is not relevant anymore.

[e-backmark-ericsson]

When working on this issue, we should also reflect on when to update our reference data sets - https://github.com/eiffel-community/eiffel/tree/master/examples/reference-data-sets/default. Preferably the data sets should reflect any properties in the events defined for a specific edition, I think.

[magnusbaeck]

Had a meeting with @e-backmark-ericsson and we broke down this issue into the following tasks:

1. Update the description of the _history.introduced_in field event-schemas.md to include information about what to do when no edition has been set.
2. Below the edition table in versioning.md add a link to event-schemas.md.
3. Add a description of the edition process that includes the following steps:
   • Verify that all issues in the milestone are closed.
   • Create a PR with the following changes (see Prepare for release of Lyon #277 for reference):
     • Changing all "No edition set" entries in the release tables of the latest YAML file for each event type to a link to the not yet existing edition tag.
     • Claim the edition in versioning.md, including a summary of what went into the edition.
   • When PR has been merged, create and push an edition-<name> annotated tag (git tag -a). The tag comment could include a short version of the included (protocol) changes. Any new major versions of event types should be called out (see Note non-backwards compatible changes in release notes #314).
   • Create a GitHub release based on the newly pushed tag. The tag comment can be reused as the release description.
   • Create issues for updating other repositories:
     • eiffel-sepia
   • Announce the new edition on mailing list, LinkedIn, and Slack and ask maintainers to update their repositories as needed.
   • Close the edition milestone.
4. In the new release management page include a section on milestones.

Other findings:

5. We should clean up the commit references in the version history tables and only use "No edition set".
6. Check if we can require tags to be annotated.
7. Rewrite description of old editions to include brief release notes.

[magnusbaeck]

We should clean up the commit references in the version history tables and only use "No edition set".

Filed as #327.

Check if we can require tags to be annotated.

This doesn't appear to be possible.

Rewrite description of old editions to include brief release notes.

Filed as #328.