* Machine readable files are efficient ways to specify protocols and data structures for Stage 3 standardization activities
## 1.1 Background
* A general term for such files (also according to ETSI Directives) is **software\***, i.e. formal definitions in some specific syntax and semantics (e.g. OpenAPI, TOSCA, YANG, etc.)
Machine readable files are efficient ways to specify protocols and data structures for Stage 3 standardization activities
* The publication of such files in Standards does not constrain implementations to make use of them for the implementation. They provide a precise definition of the expected behavior as seen from an external entity, independently from the way such behavior is implemented.
A general term for such files (also according to ETSI Directives) is **software\***, i.e. formal definitions in some specific syntax and semantics (e.g. OpenAPI, TOSCA, YANG, etc.).
* Development, coordination, governance and publication practices vary among standardization groups
The publication of such files in Standards does not constrain implementations to make use of them for the implementation. They provide a precise definition of the expected behavior as seen from an external entity, independently from the way such behavior is implemented.
* Software included in the deliverable, attached as part of a ZIP archive, referenced from a different location
* Coordination techniques include Word change tracking, email, Version Control Systems, etc.
\**The definition of the term “software” is found in the ETSI Directives v40, Annex 6, definition number 14.*
Development, coordination, governance and publication practices vary among standardization groups.
Software included in the deliverable, attached as part of a ZIP archive, referenced from a different location
Coordination techniques include Word change tracking, email, Version Control Systems, etc.
* Machine readable definitions (i.e. software) to be developed (i.e. contributed and edited) primarily using GIT repositories at ETSI Forge
* Clear and precise mapping of changes in the software with contributions on ETSI Portal
\**The definition of the term “software” is found in the ETSI Directives v40, Annex 6, definition number 14.*
* Each change in the software to tracked by a unique contribution, which holds the status in the approval process
## 1.2 Scope of the document
* Unique identification via URLs of each version of the software
This document contains the description of a process to manage contributions to ETSI deliverables via the ETSI Forge platform.
* By means of tags and branches
## 1.3 Key aspects
***Discussion and consensus building can happen offline** w.r.t. meetings, especially when dealing with editorials and minor changes
The key aspects of the process presented here are the following:
* Software can be post-processed or embedded or referenced into the deliverables **after** the changes are approved
1. Machine readable definitions (i.e. software) are developed (i.e. contributed and edited) primarily using GIT repositories at ETSI Forge, then incorporated or referenced in the deliverables;
2. Changes in the repository are univocally to contributions on ETSI Portal;
3. Each change in the repository may be tracked by a unique contribution, which holds the status in the approval process; a contribution on the ETSI Portal may reference more than one changes in the repository;
4. Each version of the content of the repository to be included or referenced in an ETSI deliverable is identified by a URL, by means of Git `tags` and/or `branches`;
5. Discussion and consensus building may happen offline w.r.t. meetings, especially when dealing with editorials and minor changes;
6. Software may be post-processed, embedded or referenced into the deliverables **after** the changes are approved;
## Contributions process to deliverables when the software is hosted in ETSI Forge
## 2 Contributions process to deliverables from ETSI Forge
### Overview of the process
### 2.1 Overview of the process
The steps below describe the process for contribution and integration of software hosted on ETSI Forge repository.
The steps below describe the process for contribution and integration of machine readable content hosted on ETSI Forge repositories.
#### 1. Reserve contribution
This activity is optional.
> OPTIONAL
The contributor reserves a contribution number on the ETSI Portal, so that it can be included in the preparation of the Merge Request.
The contributor reserves a contribution number on the ETSI Portal related to the TB/ISG and WI of interest, so that it can be included in the preparation of the Merge Request.
#### 2. Submit changes
Contributor uploads a set of changes (either modifications or additions) to the Forge platform.
The **contributor** uploads a set of changes (either modifications or additions) to the repository on the ETSI Forge.
This activity can be executed in several ways:
* Via the web interface of Gitlab (either the "Edit" button or the "Web IDE")
* Via Git (by using a Git client locally)
* Via the web interface of Gitlab (either the "Edit" button or the "Web IDE"), or
* Via Git (by using a Git client locally).
#### 3. Submit a merge request
The **contributor** creates and submits a new Merge Request in the approprate repository on the Forge Platform.
- The submitted Merge Request **shall** include:
- The changes uploaded to a branch in the repository, marked with a **given temporary name** (e.g. a `branch` or `tag` to uniquely identify the changes),
- Motivation, rationale or purpose of the changes, and
- the description of changes;
- The submitted Merge Request **may** include:
- a reserved contribution number,
- a link to a discussion or open issue in either the Forge Bugzilla bug tracker or in the integrated Gitlab bug tracker.
See clause 3 Templates for a template of a Merge Request.
#### 4. Post comment
#### 3. Contributor creates and submits a merge request in the appropriate project on ETSI Forge
#### 5. Resolve comments
- The submitted Merge Request shall include:
- The changes uploaded to a branch in the repository with a given temporary name (the branch will be deleted after the merge),
- Motivation, rationale or purpose of the changes, and the description of changes;
- It may also include:
- a contribution number (if any),
- a link to a Bugzilla issue or Gitlab issue.
#### 6. Proceed to contribution
#### 4. Contributor prepares and makes available a contribution on the Portal.
#### 7. Flag MR as Ready
#### 8. Submit or revise Contribution
Contributor prepares and makes available a contribution on the Portal.
- The submitted contribution shall include:
- Link to the Merge Request
@@ -38,28 +53,60 @@ This activity can be executed in several ways:
i. The tag to be applied after the MR is merged
ii. Changes to other elements of the deliverable (e.g. textual descriptions, tables, figures, etc.) required to maintain consistency with the changes proposed in the Merge Request.
#### 5. Contribution approval process is held leading to the approval of the contribution on the Portal;
#### 9. Contribution approval process is held leading to the approval of the contribution on the Portal;
a. If the proposed changes need revisions – either due to email discussion , or discussion during a meeting – the software on the Forge will be changed first (generating a new version) and the related contribution needs to be revised to include the pointer to the latest changes.
#### 6. The rapporteur merges the Merge request(s?) related to the approved contributions.
#### 10. Provide comment
#### 11. Note contribution
#### 12. Reject contribution
#### 13. Declare contribution approved
#### 14. Close MR request
#### 15. The rapporteur merges the Merge request(s?) related to the approved contributions.
a. NOTE: this activity may be automatized in the future but needs to take into the account the possibility of conflicts thus requiring manual intervention.
#### 7. Rapporteur applies the appropriate tag to the repository
#### 16. New draft needed
#### 17. Rapporteur applies the appropriate tag to the repository
a. With the version number of the Draft deliverable that will reference the tag
b. Note: This may be automatized
#### 8. Rapporteur updates the draft of the deliverable
#### 18. Rapporteur updates the draft of the deliverable
a. All temporary links replaced with the link to the tagged version;
b. The other elements in the approved contributions are incorporated as well, as usual.
#### 9. ETSI Secretariat receives the final draft ready for publication;
#### 19. Upload draft
#### 20. ETSI Secretariat receives the final draft ready for publication;
#### 21. ETSI Secretariat finalizes the repository, applies the publication tag and finalizes the document.
#### 10. ETSI Secretariat finalizes the repository, applies the publication tag and finalizes the document.
Checklist before applying the tag:
* Is the LICENSE file present and does it contain correct license?
* Is a README file present? If yes, does it contain the correct information (e.g. version numbers, releases, links to WIs, etc.)
* Check with the Rapporteur and TB official if there is anything else that needs to be added or modified in the repository before applying the tag
To apply the tag, use the following information:
* The tag label should be in the form "vX.Y.Z" where X Y and Z are the three version numbers
* Example: `v1.1.1`
* The tag commit messages should describe the content of the repository and the related version of the WI
* Example (fictional): `ASN.1 definitions for version 1.1.1 of ETSI 103 999`
* The release notes may contain any other information to link to the published documents
* Example: `More information and Standard downloads at https://portal.etsi.org/webapp/WorkProgram/Report_WorkItem.asp?WKI_ID=53615`
**Note: the release notes may be changed after the tag creation, while the commit message cannot be changed without deleting and recreating the tag itself.*
### Overview of the process
### Picture
A diagram showing the tasks in the process and their relations is available in the picture below.
@@ -27,4 +27,4 @@ The high-level content required or optional in a merge request and the related c
| C06 | Changes in other elements of the deliverable required to maintain consistency with the changes proposed by the MR | Optional (see note) | E.g. <br/>- Changes to a normative textual statement that explicitly calls out an attribute being removed by the Merge Request.<br/>- Changes to an example that illustrates the use of an attribute whose syntax is being changed by the Merge Request.<br/>NOTE: If the changes made to the “software” do not impact other elements, this shall be explicitly stated. |
Editor’s note: a mapping to the CR form could be done with guidance.
No newline at end of file
A mapping to the CR form with guidance is left for further study.
