Difference between revisions of "Versioning"

Latest revision as of 16:17, 23 January 2020

To ensure that permanent URLs to an attachment for a specification are readable and permanent follow the best practices listed below.

Please refer to the official guidelines at https://portal.etsi.org/Portals/0/TBpages/edithelp/Docs/editHelp%20Guidelines%20on%20Forge.pdf

In brief

GOOD examples:

Usage	Example
For the entire project	`forge.etsi.org/rep/<TB>/<SPEC>/`
For a specific version (where <VERSION> is a TAG)	`forge.etsi.org/rep/<TB>/<SPEC>/tree/<VERSION>`
For a folder within the project	`forge.etsi.org/rep/<TB>/<SPEC>/tree/<VERSION>/<FOLDER-PATH>`
For a file in the mode	`forge.etsi.org/rep/<TB>/<SPEC>/blob/<VERSION>/<FOLDER-PATH>/<FILE>`

BAD examples:

Bad practice	Example
Including the tool (Gitlab) in the tool	`forge.etsi.org/gitlab/...`
Including the version in the name of the file	`forge.etsi.org/rep/<TB>/<SPEC>/blob/<BRANCH>/my_file_vA.B.C.txt`
Using a link containing the word master (unless you know what you are doing)	`forge.etsi.org/rep/<TB>/<SPEC>/blob/master/...`

Tool independent link

Remember to use the tool independent link:

forge.etsi.org/rep/...

instead of

forge.etsi.org/gitlab/...

Use Tags!

Once the interim or final version of the work is accomplished and uploaded to the repository (see here how to do it), you should create a GIT Tag with the correct version (e.g. the version of the ETSI Deliverable).

To do so, simply visit the tags page in your project/repository (e.g. forge.etsi.org/rep/<GROUP>/<REPO>/tags ) by clicking on the Repository menu item.

In details, follow the steps:

Go to the repository
In the menu on the left, select Repository then Tags
Click on the Create Tag green button
Fill in the following information
1. Tag name: the version in a short version, e.g. v2.1.1 or TS-XYZ-ABC-v1.1.1
2. Create from: Select the correct branch or a specific revision number. Please take extra care in this selection.
3. Message: You should add a description of the version.
4. Release notes: (Optional) In case you want to provide the complete change log.

Pretty view vs Raw view

When clicking on file in a repository, the repository manager app (Gitlab) will show the contents presented in a framed box, with syntax highlighting (if supported). This is a "prettyfied" view.

In order to view the file in a "standalone" mode, i.e. the direct file only, you may want to have a "raw" view of the file. The raw view can be reached with the button at the top of the content frame as show in the figure below.

An example of YAML file in the pretty print view

An example of YAML file in the Raw view.

Do not encode versioning in the files

Do not hard code the version in the file name, e.g. DO NOT:

   my_file_v2.1.1.json

instead use

   my_file.json

and let the GIT system manage and provide the licensing information.

In the same way, it is very bad practice to keep a list of folders such as (example based on fictitious ASN.1 modules for TB XYZ):

   TB_XYZ_ASN.1_modules_v1
   TB_XYZ_ASN.1_modules_v2
   TB_XYZ_ASN.1_modules_v3
   TB_XYZ_ASN.1_modules_v4
   etc.

@@ Line 2: / Line 2: @@
 </big>
+<div style="text-align:center;border: 2px solid red;">
+<big>'''Please refer to the official guidelines at '''
+https://portal.etsi.org/Portals/0/TBpages/edithelp/Docs/editHelp%20Guidelines%20on%20Forge.pdf</big>
+</div>
 == In brief ==
@@ Line 11: / Line 15: @@
 |-
 |For the entire project
-|<code>forge.etsi.org/rep/<TB>/<SPEC>/<VERSION></code>
+|<code>forge.etsi.org/rep/<TB>/<SPEC>/</code>
+|-
+|For a specific version (where <VERSION> is a TAG)
+|<code>forge.etsi.org/rep/<TB>/<SPEC>/tree/<VERSION></code>
 |-
 |For a folder within the project
-|<code>forge.etsi.org/rep/<TB>/<SPEC>/tree/<VERSION>/<FILE></code>
+|<code>forge.etsi.org/rep/<TB>/<SPEC>/tree/<VERSION>/<FOLDER-PATH></code>
 |-
 |For a file in the mode
-|<code>forge.etsi.org/rep/<TB>/<SPEC>/blob/<VERSION>/<FILE></code>
+|<code>forge.etsi.org/rep/<TB>/<SPEC>/blob/<VERSION>/<FOLDER-PATH>/<FILE></code>
 |}
@@ Line 26: / Line 33: @@
 !Example
 |-
-|Do not include the tool (Gitlab) in the tool
+|Including the tool (Gitlab) in the tool
 |<code>forge.etsi.org/gitlab/...</code>
 |-
-|Do not include the version in the name of the file
+|Including the version in the name of the file
 |<code>forge.etsi.org/rep/<TB>/<SPEC>/blob/<BRANCH>/my_file_vA.B.C.txt</code>
 |-
-|Avoid using a link to master unless you know what you are doing
+|Using a link containing the word ''master'' (unless you know what you are doing)
 |<code>forge.etsi.org/rep/<TB>/<SPEC>/blob/master/...</code>
 |}
@@ Line 38: / Line 45: @@
 == Tool independent link ==
-Remember to use the tool independent link: <code>forge.etsi.org/rep</code>
+Remember to use the tool independent link:
+<code>forge.etsi.org/rep/...</code>
+instead of
+<code>forge.etsi.org/gitlab/...</code>
 == Use Tags! ==
-Once the final version of the file is uploaded to the repository (see [[How to add files | here how to do it]]), you want to create a GIT Tag with the correct version (e.g. the version of the ETSI Deliverable).
+Once the interim or final version of the work is accomplished and uploaded to the repository (see [[How to add files | here how to do it]]), you should '''create a GIT Tag''' with the correct version (e.g. the version of the ETSI Deliverable).
+To do so, simply visit the tags page in your project/repository (e.g. <code>forge.etsi.org/rep/<GROUP>/<REPO>/tags</code> ) by clicking on the Repository menu item.
-To do so, follow the steps:
+In details, follow the steps:
 # Go to the repository
 # In the menu on the left, select <code>Repository</code> then <code>Tags</code>
 # Click on the Create Tag green button
 # Fill in the following information
-## Tag name: the version in a short version, e.g. v2.1.1
+## Tag name: the version in a short version, e.g. v2.1.1 or TS-XYZ-ABC-v1.1.1
-## Create from: Choose the correct branch or revision! (IMPORTANT)
+## Create from: Select the correct branch or a specific revision number. Please take extra care in this selection.
-## Message: You may add a description of the version
+## Message: You should add a description of the version.
-## Release note: Optional
+## Release notes: (Optional) In case you want to provide the complete change log.
 == Pretty view vs Raw view ==

Navigation menu