Difference between revisions of "Versioning"

From ETSI Forge
Jump to: navigation, search
Line 16: Line 16:
  
 
== Pretty view vs Raw view ==
 
== 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.
 +
[[File:Gitlab Raw view button.png|center|600x600px]]
 +
[[File:Pretty view.png|alt=An example of YAML file in the pretty print view|center|thumb|An example of YAML file in the pretty print view]]
 +
[[File:Raw view.png|alt=An example of YAML file in the Raw view.|center|thumb|An example of YAML file in the Raw view.]]
  
 
== Do not encode versioning in the files ==
 
== Do not encode versioning in the files ==

Revision as of 02:59, 22 February 2019

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

Use Tags!

Once the final version of the file is uploaded to the repository (see here how to do it), you want to create a GIT Tag with the correct version (e.g. the version of the ETSI Deliverable).

To do so, follow the steps:

  1. Go to the repository
  2. In the menu on the left, select Repository then Tags
  3. Click on the Create Tag green button
  4. Fill in the following information
    1. Tag name: the version in a short version, e.g. v2.1.1
    2. Create from: Choose the correct branch or revision! (IMPORTANT)
    3. Message: You may add a description of the version
    4. Release note: Optional

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.

Gitlab Raw view button.png
An example of YAML file in the pretty print view
An example of YAML file in the pretty print view
An example of YAML file in the Raw 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.