main.md

# Scope of the document

The present document describes a process for inclusion of software hosted at the 
ETSI Forge platform in normative and informative standardization.

In the context of the present document, the term “software” shall be understood 
as one or more files that contain specifications written in a machine-processible 
form using a technical language as described in clause 7 of the ETSI Drafting Rules. 

Unless otherwise stated, use of such technical languages in a deliverable is not 
intended to constrain implementations to make use of this language to claim 
compliance with the deliverable.

The goal is to enable ETSI TBs and ISGs to adopt best practices for management 
of machine readable content when dealing with formal and machine-readable languages 
in the specification process.
The foreseen benefit is to have a more efficient standardization process  avoid 
multiple  of content and costly maintenance.

In particular it addresses the problem of duplication of versions and sources 
for software: the proposed approach follows the principle of writing the same 
information only once.
The main focus of the process proposed below is to ensure traceability and 
transparency of contributions and change approval of the deliverable referencing 
or including software hosted at ETSI Forge.

The definition of the term “software” is found in the ETSI Directives v40, 
Annex 6, definition number 14.

# Contributions to deliverables when the software is hosted in ETSI Forge 

## Overview of the process

The steps below describe the process for contribution and integration of software hosted on ETSI Forge repository.

### 1. (Optional) Contributor reserves a contribution number on the ETSI Portal
### 2. Contributor creates and submits a merge request in the appropriate project on ETSI Forge

  - 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.

### 3. Contributor prepares and makes available a contribution on the Portal.
  - The submitted contribution shall include:
    - Link to the Merge Request
    - Reference in the text to the location of the changed software, i.e. the changes in the target deliverable which include the links to the new version of the software in the named branch linked to the MR
EXAMPLE: Merge request XYZ proposes to merge branch FEAT1 into branch v1.1.x and is to be approved in contribution (19)00000ABC. The contribution will contain the changes in the base deliverable with the URLs updated to point to forge.etsi.org/rep/TB/DOCNUM/tree/FEAT1
b.	It may include
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.

### 4. 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. 

### 5. 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.

### 6. 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

### 7. 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.

### 8. ETSI Secretariat receives the final draft ready for publication;

### 9. ETSI Secretariat finalizes the repository, applies the publication tag and finalizes the document.
 
## Templates of a contribution for software

The high-level content required or optional in a merge request and the related contribution is described in the clauses below.

###  Merge request

| Id | Field | Provision | Description |
| ---| ----- |  -------  | -----------:|
|M01 | Unique URL | Mandatory |	E.g. <forge>/<my-group>/<my-project>/merge_requests/<ID> |
|M02 | Diff : Changes in the software | Mandatory	|  |
|M03 | Motivation, rationale or purpose of the changes | |		
|M04 | Description of the changes |	Mandatory	|    |
|M05 | Green light from CI Validation |	Mandatory | |	
|M06 | Software URL |	Mandatory |	E.g. <forge>/<my-group>/<my-repo>/0.0.x |
|M07 | Reserved contribution number in the Merge request documentation	| Optional | |	
|M08 | Link to Bugzilla or Gitlab issue |	Optional	|  |

### Contribution to the Portal

Id	Field	Provision	Description
C01	Link to MR so that software can be reviewed	Mandatory	
C0x	Reason for Change	Mandatory
If the contribution does not propose any change beyond those in the Merge Request, this field can refer to the Reason for Change of the Merge Request.
C0x	Description of the Change	Mandatory
If the contribution does not propose any change beyond those in the Merge Request, this field can refer to the Description of  Change of the Merge Request.
C02	Number of the latest commit in the merge request	Mandatory	
C03	Changes in the text pointing to the software 
Mandatory
	E.g.:Data model A is available at <forge>/ <my-group>/ <my-project>/ <my-title>/ A.yaml”
C04	Changes in other elements of the deliverable required to maintain consistency with the changes proposed by the MR	Optional
(see note)	e.g. 
- Changes to a normative textual statement that explicitly calls out an attribute being removed by the Merge Request.

- Changes to an example that illustrates the use of an attribute whose syntax is being changed by the Merge Request. 
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.

## Details of the activities

### Rapporteur Merge and tag changes

•	Merge approved Merge Requests
•	Tag with new draft number e.g. 0.0.2

### Create new draft

•	Apply text changes
•	Search and replace any occurrence of <forge>/my-group/my-project/<whatever>/ to <forge>/my-group/my-project/v0.0.2/

# Branching and tagging strategy

•	Published versions should be tagged with the publication version, e.g. 1.1.1
o	Published tags should allow for editorials to be fixed and to issue a new branch, e.g. 1.1.1-1
•	Publication branch i.e. the branch containing the publishable /published versions of the files.

## Usage of TAGs

### Role of tags

Git tags are a construct to label a specific revision (or commit) in a repository for quick and user-friendly references.
By their nature, they are well suited to identify revisions of the software in the repository and to map them to the steps of the approval process (e.g. meeting references, contribution references, etc.) or drafts of the deliverable they are related to.

### Guidelines

Drafting tags and publication tags should be protected, i.e. they are applicable by privileged users, which may be the Rapporteur of the related document, “power users” nominated by the TB or members of ETSI Secretariat.
o	NOTE 1: The definition of tag name templates is left for future study
o	NOTE 2: TAGs, once applied shall not be removed and re-applied (though technically possible). 

## Usage of branches

1.	Publication branch (name: master?)
2.	Publication branch for other release (e.g. Release-XY)
3.	Drafting branch (name: Drafting? Or draft “family” such as 0.0.x)