Initial procedure draft

## Contributions process to specs

### Overview of the process

The steps below describe the process for contribution and integration of Change Requests using GitLab repositories.

#### 1. Contributor reserve a contribution name in the ETSI portal

The contributor generates a new CR in the ETSI portal so that a **contribution name** is generated (e.g. "MEC(25)000001-My_contribution_title").

#### 2. Contributor creates a new branch for changes

The contributor creates a new branch for the contribution. See [Gitlab's branching documentation for more details](https://docs.gitlab.com/ee/user/project/repository/branches/).

The branch shall be based on the **latest tag of the release candidate branch** as start point.

The branch name shall reflect to **contribution name** generated by the ETSI portal in the previous step (so, "MEC(25)000001-My_contribution_title").

#### 3. Contributor commits changes to the branch

The contributor makes a set of changes (either modifications or additions) to the newly-created branch.

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)

A contribution can be composed of a set of commits or just one commit that includes all desired changes.

#### 4. Contributor creates and submits a merge request

The contributor, once the contribution is ready, raises a **Merge Request** from the branch containing their changes named as the contribution branch ("MEC(25)000001-My_contribution_title") against the release candidate branch where the contribution branch was created from (e.g. "R5").

The submitted Merge Request shall include some description by filling the simplified contribution template.

> Note: At this point of time, there are two coversheet contribution templates, a complete coversheet template and a simplified coversheet template. For the latter, the pipeline will use information taken from the **Merge Request**. Fields not present in the simplified template can be added and those will take priority against the information taken from the **Merge Request**.  

In addition, if contributor needs to add more explanation to the contribution, a comment can be added, which will be inserted into the autogenerated CR. 

The submission of the **Merge Request** will automatically lock the source contribution branch so that it cannot be modified anylonger (Note that this is DEACTIVATED for the time being). 

#### 5. Contributor prepares and makes available a contribution on the ETSI Portal.

The contributor uploads the autogenerated CR to the ETSI portal. This autogenerated CR contains the changes submitted, the contribution details as coverpage and a link to the new **Merge Request**.

> Note: The autogenerated CR should be reviewed before submitting it in order to verify its completeness. 

For example, Merge request CR1 proposes to merge branch "CR1" into branch Release-X (latest status which is tagged as vX.Y.Z version). 

#### 6. The usual contribution approval process of document is held leading to the approval of the contribution on the Portal (and minuted in the meeting report)

The rapporteur applies the Merge Request CR1. 

In case of conflict, the rapporteur fixes the conflict by rebasing the contribution branch and/or fixing the conflict locally. <mark>The contribution needs to go to the normal approval process once again.</mark>

#### 7. The usual contribution approval process of document is held leading to revisions required – either due to email discussion , or discussion during a meeting

The contributor shall rename the **Merge Request** to include the revision number, CR1r01 (it reflects that the **Merge Request** is being revised), and then the contribution branch is unlocked (unprotected) so that the contributor can submit the required revisions. No new contribution branch nor branch renaming is needed. Once the revision is ready (all necessary commits have been done to the contribution branch), the contributor runs a new pipeline for the **Merge Request**. The autogenerated revised CR shall be submitted to the ETSI portal. The process continues to step 6.

> Note: Each pipeline run will make the contribution branch be locked again.

#### 8. The usual contribution approval process of document is held leading to the rejection of the contribution (and minuted in the meeting report)

The rapporteur closes the Merge Request CR1. 

#### 9. Rapporteur produces a new draft

The production of a new draft requires the following steps from the rapporteur: 

1. Update of date, version number and history directly on the release branch

1. Creation of a new tag on the release branch named vX.A.B.

1. Upload of the newly autogenerated draft to the ETSI Portal

```mermaid

graph TB

  classDef gitlab fill:#f90,stroke:#333,stroke-width:3px

  start("Start")

  reserve["Reserve 'contribution name' in ETSI portal"]

  createBranch["Create contribution branch<br />named as 'contribution name' "]

  submitChanges["Submit/update changes<br />to contribution branch"]

  hasComments["If public,<br />comments might already be provided"]

  isReady{"Is contribution<br />ready?"}

  reject["Declare rejected"]

  approve["Declare approved"]

  revision("WG discuss contribution")

  approval{"Is contribution<br />approved?"}

  submitContrib["Create Merge-request<br />named as contribution branch"]

  blockContribution["Lock contribution branch"]

  unlockMR["Unlock contribution branch"]

  uploadCR["Upload CR to ETSI portal<br />(autogenerated in Merge-request)"]

  reviseContrib["Rename Merge-request<br />to add revision number"]

  existsMR{"Does a Merge-request<br />exist?"}

  closeMR["Close Merge-request"]

  applyMR["Apply Merge-request"]

  newDraft{"New draft?"}

  makeDraft["Tag release branch"]

  draft["Rapporteur prepares a the new draft:<br > Update version, date and history "]

  draftAvailable["Rapporteur uploads the newly draft to the ETSI Portal"]

  stop("Stop")

  conflict{"Is there any conflict?"}

  fixConflict["Rebase contribution branch/fix conflict"]

  class createBranch,submitChanges,blockContribution,submitContrib,unlockMR,reviseContrib,applyMR,fixConflict,makeDraft,draft,closeMR gitlab;

  start-->reserve

  reserve-->createBranch

  createBranch-->submitChanges

  hasComments-->submitChanges

  submitChanges-->isReady

  isReady--Ready-->blockContribution

  blockContribution-->existsMR

  existsMR--Yes-->uploadCR

  existsMR--No-->submitContrib

  isReady--"comments or not finished"-->submitChanges

  uploadCR-->revision

  submitContrib-->uploadCR

  revision-->approval

  approval--Yes-->approve

  approval--No-->reject

  approve-->applyMR

  applyMR-->conflict

  approval--"Revision required"-->reviseContrib

  reviseContrib-->unlockMR

  unlockMR-->submitChanges

  reject-->closeMR

  closeMR-->stop

  conflict--No-->newDraft

  conflict--Yes-->fixConflict

  fixConflict-->revision

  newDraft--Yes-->draft

  draft-->makeDraft

  newDraft--No-->stop

  makeDraft-->draftAvailable

  draftAvailable-->stop

```