New version of the process, tabular version for the templates and other improvements

# Background

* Machine readable files are efficient ways to specify protocols and data structures for Stage 3 standardization activities

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

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

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

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

* 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

* Each change in the software to tracked by a unique contribution, which holds the status in the approval process

* Unique identification via URLs of each version of the software

* By means of tags and branches

* **Discussion and consensus building can happen offline** w.r.t. meetings, especially when dealing with editorials and minor changes

* Software can be post-processed or embedded or referenced into the deliverables **after** the changes are approved

# Forge contributions documentation

Repository to document the process, activities, actors and deliverables of the contribution of software on the Forge.

Starts with [main.md](main.md).

## How to contribute

Contributions and feedback are welcome!

1. Visit the main page of the process and click "Request access"

2. Use Issues and Merge Requests to provide feedback and input

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

### 1.  Reserve contribution 

This activity is optional. 

The contributor reserves a contribution number on the ETSI Portal, 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.

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)

### 3. 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),

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

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

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;

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

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

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

### 8. 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 receives the final draft ready for publication;

### 10. ETSI Secretariat finalizes the repository, applies the publication tag and finalizes the document.

## Picture

### 9. ETSI Secretariat finalizes the repository, applies the publication tag and finalizes the document.

![Proposed process](imgs/process1.png "Proposed process")

## Templates of a contribution for software

| Id | Field | Provision | Description |

| ---| ----- |  :------  | :-----------|

|M01 | Unique URL | Mandatory |	E.g. <forge>/<my-group>/<my-project>/merge_requests/<ID> |

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

|M06 | Software version 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	|  |

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

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

| C04  | Number of the latest commit in the merge request             | Mandatory           |                                                              |

| C05  | 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” |

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

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

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

- 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