Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Eclipse UML Generators/Specifications/Template"
m (→Backward Compatibility and Migration Paths) |
|||
| (One intermediate revision by one other user not shown) | |||
| Line 1: | Line 1: | ||
| − | = Evolution Specification: | + | = Evolution Specification: Title of the evolution = |
Current status is '''DRAFT''' | Current status is '''DRAFT''' | ||
| Line 5: | Line 5: | ||
== Preamble == | == Preamble == | ||
| − | + | ''Summary'': a short one-sentence summary of what this evolution is about. | |
| − | <br> | + | <br> The possible status are (roughly inspired by [http://python.org/dev/peps/pep-0001/ PEP-0001]): |
| − | ''' | + | *'''DRAFT''': Initial version and revisions based on internal feedback and discussions. DRAFT versions may never be completed. They have version numbers 0.x. |
| − | * | + | *'''PROPOSAL''': When the document is considered ready for discussion with the community, it becomes a PROPOSAL. The first such version is numbered 1.0. Feedback from the community are integrated in further versions 1.x which are still PROPOSALs. Changes from one version to the next should be documented inside the document (as the community does not have access to the source repository). |
| − | + | *'''ACCEPTED''': Once agreement has been reached with the community, the document becomes ACCEPTED.This version becomes the authoritative one for guiding the evolution's actual implementation. It should normally be considered freezed. Any change to it should be exceptional and subject to approval by the project manager. Such changes must be clearly documented and justified. | |
| − | + | *'''ARCHIVED''': Once the evolution has been implemented _and_ its specification has been integrated into the reference documentation, this document is ARCHIVED. Any further change to the same features should be another __evolution__ . | |
| − | + | ||
| − | + | _Relevant tickets_ (links to the Bugzilla tickets which are related to the change): | |
| − | * | + | |
| − | + | *[https://bugs.eclipse.org/bugs/show_bug.cgi?id=438003 Bug 438003] - initial contribution | |
| − | + | ||
| + | == Introduction == | ||
| + | |||
| + | This section should contain a summary of the proposed evolution, including why it is needed. Ideally it should be self-contained so that non-developers can get a quick overview of the evolution without reading the detailed specification. | ||
== Detailed Specification == | == Detailed Specification == | ||
| Line 32: | Line 34: | ||
== Backward Compatibility and Migration Paths == | == Backward Compatibility and Migration Paths == | ||
| + | |||
| + | Every one of the sections below should be present. Even if there is no corresponding change (for example no API change), it should exist to mention explicitly "This evolution does not change any API." | ||
=== Metamodel Changes === | === Metamodel Changes === | ||
| − | + | Document any change to the Viewpoint metamodel. If they require a migration operation, mention it and describe the general idea of how migration process. If any information can be lost during the migration, mention it clearly. If validation rules must be added/modified, mention it also. | |
=== API Changes === | === API Changes === | ||
| − | + | List every API addition, removal and deprecation. For each removal and deprecation, indicate the migration path for existing code. | |
=== User Interface Changes === | === User Interface Changes === | ||
| − | + | List every user-visible change in the interface. Here "user" includes not only end-users but also developpers. | |
| − | + | ||
| − | + | ||
=== Documentation Changes === | === Documentation Changes === | ||
| − | List every documentation needing an update here, starting by the New and Noteworthy documentation. | + | List every documentation needing an update here, starting by the New and Noteworthy documentation. |
== Tests and Non-regression strategy == | == Tests and Non-regression strategy == | ||
Latest revision as of 11:42, 31 July 2014
Evolution Specification: Title of the evolution
Current status is DRAFT
Preamble
Summary: a short one-sentence summary of what this evolution is about.
The possible status are (roughly inspired by PEP-0001):
- DRAFT: Initial version and revisions based on internal feedback and discussions. DRAFT versions may never be completed. They have version numbers 0.x.
- PROPOSAL: When the document is considered ready for discussion with the community, it becomes a PROPOSAL. The first such version is numbered 1.0. Feedback from the community are integrated in further versions 1.x which are still PROPOSALs. Changes from one version to the next should be documented inside the document (as the community does not have access to the source repository).
- ACCEPTED: Once agreement has been reached with the community, the document becomes ACCEPTED.This version becomes the authoritative one for guiding the evolution's actual implementation. It should normally be considered freezed. Any change to it should be exceptional and subject to approval by the project manager. Such changes must be clearly documented and justified.
- ARCHIVED: Once the evolution has been implemented _and_ its specification has been integrated into the reference documentation, this document is ARCHIVED. Any further change to the same features should be another __evolution__ .
_Relevant tickets_ (links to the Bugzilla tickets which are related to the change):
- Bug 438003 - initial contribution
Introduction
This section should contain a summary of the proposed evolution, including why it is needed. Ideally it should be self-contained so that non-developers can get a quick overview of the evolution without reading the detailed specification.
Detailed Specification
This section contains the "meat" of the document. Its structure will depend on the evolution itself, but it should contain:
- a clear description of the objective, i.e. why the evolution is needed.
- a justification of the approach chosen. If other approaches were considered and rejected, document it for future reference.
- limits: things that are out of the scope of the evolution.
Backward Compatibility and Migration Paths
Every one of the sections below should be present. Even if there is no corresponding change (for example no API change), it should exist to mention explicitly "This evolution does not change any API."
Metamodel Changes
Document any change to the Viewpoint metamodel. If they require a migration operation, mention it and describe the general idea of how migration process. If any information can be lost during the migration, mention it clearly. If validation rules must be added/modified, mention it also.
API Changes
List every API addition, removal and deprecation. For each removal and deprecation, indicate the migration path for existing code.
User Interface Changes
List every user-visible change in the interface. Here "user" includes not only end-users but also developpers.
Documentation Changes
List every documentation needing an update here, starting by the New and Noteworthy documentation.
Tests and Non-regression strategy
This part of the document should describe the strategy to use to correctly test the evolution and guarantee the non-regression.
Implementation choices and tradeoffs
Any important tradeoff or choice made during the implementation should be referenced here with pros/cons leading to the final decision.