Document release process for editions (#325)

Author: magnusbaeck

README.md

@@ -86,3 +86,5 @@ Visit [Eiffel Community](https://eiffel-community.github.io) to get started and
    1. [Custom Data](./customization/custom-data.md)
 1. Extensions
    1. [Eiffel Operations Extension](https://github.com/Ericsson/eiffel-operations-extension)
+1. Releases and Milestones
+   1. [Release process](./releases-and-milestones/release-process.md)

eiffel-syntax-and-usage/event-schemas.md

@@ -35,7 +35,7 @@ Both schemas and documentation files are generated from _schema definition files
 | `_links.<link type>.targets.types`     | A string array of event names that the link type may point to. Must be non-empty if `any_type` is false, and must be empty if `any_type` is true. |
 | `_history`      | An array of objects describing the event type's version history, up to and including the current version. The items should be sorted in reverse order. |
 | `_history.version`        | The event version described in this item. |
-| `_history.introduced_in`  | A description of the edition in which this item's event version was introduced. |
+| `_history.introduced_in`  | The first edition in which this version was the latest for this event type. If the version hasn't been released in a protocol edition or if there are newer versions in the first edition where it was introduced, use "No edition set". |
 | `_history.changes`        | A short description of the changes in this item's event version. | 
 | `_examples`     | An array of objects describing examples of this event. |
 | `_examples.title`         | The name of the example. |

eiffel-syntax-and-usage/versioning.md

@@ -39,6 +39,8 @@ That being said, to facilitate compatibility and consistency, the Eiffel protoco
 | Toulouse  | [edition-toulouse](../../../tree/edition-toulouse)  | Stepped major version of TERCC. Updated FLOW_CONTEXT link type, resulting in new minor version of all event types. |
 | Bordeaux  | [edition-bordeaux](../../../tree/edition-bordeaux)  | Initial edition. |
 
+The [schema definition files](event-schemas.md) document the mappings between event versions and editions.
+
 ## Rules for patch, minor and major versions
 In the case of a communication protocol, applying Semantic Versioning is not as straight-forward as for a regular software implementation. The ground rule is to consider backwards compatibility from the perspective of the consumer of an event. Below are rules and examples of how this applies to the Eiffel protocol.
 

releases-and-milestones/release-process.md

@@ -0,0 +1,41 @@
+<!---
+   Copyright 2022 Axis Communications AB.
+   For a full list of individual contributors, please see the commit history.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+--->
+
+# Release process
+
+This document describes the release process for Eiffel editions.
+
+## Pre-release activities
+
+Look up the name of the next edition in the [Versioning](../eiffel-syntax-and-usage/versioning.md) document.
+
+GitHub [milestones](https://github.com/eiffel-community/eiffel/milestones?state=open) are used to track the proposed contents of an upcoming edition. Milestones are named "Edition \<name>", e.g. "Edition Arica". Issues, not pull requests, are added to the milestone.
+
+## Making a release
+
+When all issues in the scope of the edition have been closed and it's time to make the release, follow these steps:
+
+1.  Verify that all issues in the [milestone](https://github.com/eiffel-community/eiffel/milestones?state=open) are closed.
+1.  Create a pull request with the following changes (see [PR 277](https://github.com/eiffel-community/eiffel/pull/277) for reference):
+    1.  Change 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.
+    1.  Claim the edition in [versioning.md](../eiffel-syntax-and-usage/versioning.md), including a short summary of the changes in the edition.
+1.  When the pull request has been merged, create and push an "edition-\<name>" annotated tag (use `git tag -a`). The tag comment could include a short version of the included changes to the protocol. Any new major versions of event types should be called out.
+1.  Create a GitHub release based on the newly pushed tag. The tag comment can probably be reused as the release description.
+1.  Create issue(s) for updating other repositories to reference the new edition:
+    1. [eiffel-sepia](https://github.com/eiffel-community/eiffel-sepia)
+1.  Announce the new edition on the eiffel-community mailing list, LinkedIn, and Slack and ask maintainers of other repositories to make necessary updates.
+1.  Mark the edition's milestone as closed.