This is a static archive of the previous Open Grid Forum Redmine content management system saved from host redmine.ogf.org file /projects/glue-wg/wiki/Enumerations_procedures_and_best_practices_v11/annotate/3 at Fri, 04 Nov 2022 15:14:44 GMT GLUE WG - Open Grid Forum

Enumerations procedures and best practices v11

Version 3 (Florido Paganelli, 06/18/2014 08:31 AM)

1 1 Shiraz Memon
{{>toc}}
2 1 Shiraz Memon
3 3 Florido Paganelli
| *NOTE*: this is a work in progress page. The official documentation is here: http://redmine.ogf.org/projects/glue-wg/wiki/Enumerations_procedures_and_best_practices_v10 |
4 1 Shiraz Memon
5 2 Florido Paganelli
h1. OGF GLUE2 Enumerations procedures and best practices
6 1 Shiraz Memon
7 2 Florido Paganelli
Author: Florido Paganelli florido.paganelli_REMOVE!THIS_@hep.lu.se
8 1 Shiraz Memon
9 3 Florido Paganelli
version:1.1rc0
10 1 Shiraz Memon
11 3 Florido Paganelli
Document Status: Draft
12 1 Shiraz Memon
13 2 Florido Paganelli
Last revision: 2014-06-18
14 1 Shiraz Memon
15 2 Florido Paganelli
h2. 1. Introduction
16 1 Shiraz Memon
17 2 Florido Paganelli
This work is an attempt to summarize and generalize the usage of Open Enumerations in GLUE2, and an attempt to set some rules on how the management of these should be carried on.
18 1 Shiraz Memon
19 2 Florido Paganelli
The key words ‘MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD NOT,” “RECOMMENDED,” “MAY,” and “OPTIONAL” are to be interpreted as described in RFC 2119 (see http://www.ietf.org/rfc/rfc2119.txt).
20 1 Shiraz Memon
21 2 Florido Paganelli
h3. 1.1. Acknowledgements
22 1 Shiraz Memon
23 2 Florido Paganelli
Thanks to Stephen Burke, David Meredith, Paul Millar and Balazs Konya for kickstart of these ideas and their further development. Thanks to John-Paul Navarro and Shiraz Memon for coordinating this work within the OGF GLUE2 Working Group. Thanks to Andre Merzky for comments.
24 1 Shiraz Memon
25 2 Florido Paganelli
h2. 2. Naming Schemes
26 1 Shiraz Memon
27 2 Florido Paganelli
The following rules apply:
28 1 Shiraz Memon
29 2 Florido Paganelli
# Every string is RECOMMENDED to be lowercase.
30 2 Florido Paganelli
# Clients MUST consider these strings case-sensitive as defined in "GFD.147":http://www.ogf.org/documents/GFD.147.pdf.
31 2 Florido Paganelli
# Case MUST NOT be used as a way to distinguish strings; in practice, the group will not accept names that only differ in case.
32 2 Florido Paganelli
33 2 Florido Paganelli
h3. 2.1. Services
34 2 Florido Paganelli
35 2 Florido Paganelli
This applies to the GLUE2 Open Enumeration @ServiceType_t.@
36 2 Florido Paganelli
37 2 Florido Paganelli
See also "GFD.147":http://www.ogf.org/documents/GFD.147.pdf, Appendix B.31
38 2 Florido Paganelli
39 2 Florido Paganelli
   <pre><organization_name>.<product_name>.<service_detail></pre>
40 2 Florido Paganelli
41 2 Florido Paganelli
where
42 2 Florido Paganelli
43 2 Florido Paganelli
@<organization_name>@ 
44 2 Florido Paganelli
is the reversed domain name of the organization which provides or maintains the service or a reversed domain name associated with the project.
45 2 Florido Paganelli
Presence: *RECOMMENDED* for *new* names. Exceptions MUST be justified.
46 2 Florido Paganelli
47 2 Florido Paganelli
@<product_name>@ 
48 2 Florido Paganelli
free form string for product names
49 2 Florido Paganelli
Presence: *MANDATORY*
50 2 Florido Paganelli
51 2 Florido Paganelli
@<service_detail>@ 
52 2 Florido Paganelli
free form string that SHOULD identify a subservice or a service implementation. It can contain dots.
53 2 Florido Paganelli
Presence: *OPTIONAL*
54 2 Florido Paganelli
55 2 Florido Paganelli
Decision: *RECOMMENDED* requirement is 
56 2 Florido Paganelli
57 2 Florido Paganelli
<pre><organization_name>.<product_name></pre>
58 2 Florido Paganelli
59 2 Florido Paganelli
Examples: @org.nordugrid.arex, org.glite.ce.cream@
60 2 Florido Paganelli
61 2 Florido Paganelli
Existing names not following the above rules can be kept, but MAY be Deprecated to be consistent with recommendations. (see Section [[Enumerations_procedures_and_best_practices_v10#24-Sorting-out-special-classes-of-names|2.4]] and Section [[Enumerations_procedures_and_best_practices_v10#4-Management-of-Open-Enumerations|4]])
62 2 Florido Paganelli
63 2 Florido Paganelli
h3. 2.2. Interfaces
64 2 Florido Paganelli
65 2 Florido Paganelli
This applies to the GLUE2 Open Enumeration @InterfaceName_t.@
66 2 Florido Paganelli
GFD.147 Appendix B.18 does not define any clear format. The following is RECOMMENDED:
67 2 Florido Paganelli
<pre><organization_name>.<interface_name></pre>
68 2 Florido Paganelli
69 2 Florido Paganelli
where:
70 2 Florido Paganelli
71 2 Florido Paganelli
@<organization_name>@
72 2 Florido Paganelli
is the reversed domain name of the organization which provides or maintains the service or a reversed domain name associated with the project.
73 2 Florido Paganelli
Presence: *RECOMMENDED* for *new* names. Exceptions MUST be justified.
74 2 Florido Paganelli
75 2 Florido Paganelli
@<interface_name>@
76 2 Florido Paganelli
free form string for product names
77 2 Florido Paganelli
Presence: *MANDATORY*
78 2 Florido Paganelli
79 2 Florido Paganelli
Examples: @org.nordugrid.xbes, org.ogf.glue.emies.activitycreation, org.glite.voms@
80 2 Florido Paganelli
81 2 Florido Paganelli
h3. 2.3. Capabilities
82 2 Florido Paganelli
83 2 Florido Paganelli
See "GFD.147":http://www.ogf.org/documents/GFD.147.pdf , appendix B.5, on @Capability_t@.
84 2 Florido Paganelli
85 2 Florido Paganelli
h3. 2.4. Sorting out special classes of names
86 2 Florido Paganelli
87 2 Florido Paganelli
h4. In case the organization name is unknown/undefined/short-lived 
88 2 Florido Paganelli
89 2 Florido Paganelli
Use the reserved prefix:
90 2 Florido Paganelli
91 2 Florido Paganelli
    org.ogf.glue.
92 2 Florido Paganelli
93 2 Florido Paganelli
@org.ogf.glue.*@ SHOULD be used if the proposed domain name is not applicable. Examples are expired/nonexistent/unregistered domains, domains that have been used for other purposes than the proposed product, and so on. The group can decide case by case.
94 2 Florido Paganelli
95 2 Florido Paganelli
Example:For EMIR, developed during EMI project that now is over, @ServiceType_t@ is: @org.ogf.glue.emir@
96 2 Florido Paganelli
97 2 Florido Paganelli
If a project ends and the product has an orphaned reverse domain name, the name can be kept.
98 2 Florido Paganelli
99 2 Florido Paganelli
h4. Simplified naming for Services with only one Interface
100 2 Florido Paganelli
101 2 Florido Paganelli
A specific Endpoint interface can be bound to a specific Service. In such case, to simplify name creation, @InterfaceName_t@ MAY be the same of a corresponding @ServiceType_t.@
102 2 Florido Paganelli
103 2 Florido Paganelli
h2. 3. Requesting new Open Enumerations
104 2 Florido Paganelli
105 2 Florido Paganelli
A community willing to submit new open enumeration MUST:
106 2 Florido Paganelli
107 2 Florido Paganelli
# Provide the following information about the enumeration to be submitted:
108 2 Florido Paganelli
** *Type* of the enumeration to be added (i.e. one of the types described in "GFD.147":http://www.ogf.org/documents/GFD.147.pdf, Appendix B )
109 2 Florido Paganelli
** *Name* of the enumeration as in the guidelines in [[Enumerations_procedures_and_best_practices_v10#2-Naming-Schemes|Section 2]];
110 2 Florido Paganelli
** *Description* of the enumeration. This description is a textual, human readable summary of what the object described by the open enumeration does. It SHOULD be provided in two parts: a concise description that will be stored as part of the definition of the enumerated types, and a (usually) longer description that will explain to the WG what the new type is for.
111 2 Florido Paganelli
** *Reference email* to be contacted by the OGF group during evaluation of the proposed strings. This email will not be published and will be internal to the group.
112 2 Florido Paganelli
# Send the above information to the OGF group at the address glue-wg@ogf.org with subject @“[Enumerations] Request for addition/obsoletion/modification”@
113 2 Florido Paganelli
114 2 Florido Paganelli
*NOTE:* Requests that are missing the information listed in 1 will be automatically rejected. The proposer will be asked to provide missing information.
115 2 Florido Paganelli
116 2 Florido Paganelli
h2. 4. Management of Open Enumerations
117 2 Florido Paganelli
118 2 Florido Paganelli
The group preserves the current list of Open Enumerations in the git repository at the link
119 2 Florido Paganelli
120 2 Florido Paganelli
bq. https://github.com/OGF-GLUE/Enumerations
121 2 Florido Paganelli
122 2 Florido Paganelli
in the form of CSV files. Section 4.1 contains a description of the content of the CSV files.
123 2 Florido Paganelli
124 2 Florido Paganelli
The groups keeps them updated using the procedures listed in this document, defined in [[Enumerations_procedures_and_best_practices_v10#43-GLUE2-Working-Group-Procedures|Section 4.3]].
125 2 Florido Paganelli
126 2 Florido Paganelli
h3. 4.1. Description of Open Enumerations CSV files
127 2 Florido Paganelli
128 2 Florido Paganelli
CSV filenames in git-hub are of the form:
129 2 Florido Paganelli
130 2 Florido Paganelli
|_.Filename |_.Purpose |_.Example | 
131 2 Florido Paganelli
| @<EnumerationName_t>.csv@ |  Contains Open Enumerations officially approved by the group. | @ServiceType_t.csv@ |
132 2 Florido Paganelli
| @<EnumerationName_t>-draft.csv@ | Contains Open Enumerations approved by the group AND Open Enumerations pending approval from the group | @ServiceType_t-draft.csv@ |
133 2 Florido Paganelli
134 2 Florido Paganelli
Records contained in the CSV files are as follows:
135 2 Florido Paganelli
136 2 Florido Paganelli
# The first row always contain the following strings:
137 2 Florido Paganelli
>> @EnumerationType,EnumerationValue,Description,Status,Recommended, Deprecated@
138 2 Florido Paganelli
# Rows from the second on contains the following:
139 2 Florido Paganelli
140 2 Florido Paganelli
|_.Field Name |_.Purpose |_.Example | 
141 2 Florido Paganelli
| @EnumerationType@ | Enumeration Type name. MUST be the same as in the filename. | @ServiceType_t@ |
142 2 Florido Paganelli
| @EnumerationValue@ | It's the enumeration value. | @org.nordugrid.arex@ |
143 2 Florido Paganelli
| @Description@ | Contains the textual description of the object represented by the enumeration name. | @NorduGrid Resource Coupled Execution Service@ |
144 2 Florido Paganelli
| @Status@ | See discussion below. | @Recommended@ |
145 2 Florido Paganelli
| @Recommended@ | If this field is NOT EMPTY, then the contained string SHOULD be used instead of the EnumerationValue. | @org.nordugrid.arex@ |
146 2 Florido Paganelli
| @Deprecates@ | If the field is NOT EMPTY, then the EnumerationValue string SHOULD be used instead of the contained values. | @org.nordugrid.execution.arex@ |
147 2 Florido Paganelli
148 2 Florido Paganelli
h3. 4.2. Statuses
149 2 Florido Paganelli
150 2 Florido Paganelli
*Terminology:*
151 2 Florido Paganelli
*Information/service provider* = software that produces the GLUE2 entries.
152 2 Florido Paganelli
*Information consumers* = software that reads some GLUE2 information source.
153 2 Florido Paganelli
154 2 Florido Paganelli
*Description of Statuses*
155 2 Florido Paganelli
156 2 Florido Paganelli
*Recommended:* The EnumerationValue string SHOULD be used in production systems by both service providers and consumers.
157 2 Florido Paganelli
158 2 Florido Paganelli
*Deprecated:* The EnumerationValue string SHOULD NOT be used anymore, but is still used in production systems. 
159 2 Florido Paganelli
Information providers are advised to change to the value present in the Recommended column.
160 2 Florido Paganelli
Information consumers SHOULD temporarily accept or expect both the Deprecated and the Recommended strings.
161 2 Florido Paganelli
162 2 Florido Paganelli
*Obsolete:* The string, and possibly the related represented entity, are not used in production anymore and SHOULD NOT be published by providers or accepted by consumers. This is mainly used for historical record. It is NOT RECOMMENDED to re-use an Obsolete name, as it might be reactivated for the same use.
163 2 Florido Paganelli
164 2 Florido Paganelli
Status might contain multiple values, represented as multilined fields in the CSV.
165 2 Florido Paganelli
166 2 Florido Paganelli
Status MUST NOT be both Recommended and Deprecated. The only allowed combinations are:
167 2 Florido Paganelli
168 2 Florido Paganelli
*Recommended Obsolete*: The EnumerationValue string is valid but the type is not in use anymore. Equivalent to Obsolete.
169 2 Florido Paganelli
170 2 Florido Paganelli
*Deprecated Obsolete*:  The EnumerationValue string SHOULD NOT be used anymore. The corresponding item is not used anymore. Information providers SHOULD NOT publish this value, and information consumers SHOULD NOT use it.
171 2 Florido Paganelli
172 2 Florido Paganelli
h3. 4.3. GLUE2 Working Group Procedures
173 2 Florido Paganelli
174 2 Florido Paganelli
# When a request arrives, a selected member of the group adds the names to @<EnumerationType_t>-draft.csv@ document. (e.g. ServiceType_t-draft.csv).
175 2 Florido Paganelli
These values will have no value in the Status column inside the -draft.csv document.
176 2 Florido Paganelli
# Promptly upon arrival the group decides about the feasibility of adding the values.
177 2 Florido Paganelli
Enumerations in draft state can be used by users but are in the process of being accepted. Consumers can use them at their own risk. 
178 2 Florido Paganelli
If the values are accepted, the Status field SHOULD contain  one of Recommended, Deprecated or Obsolete according to [[Enumerations_procedures_and_best_practices_v10#42-Statuses |Section 4.2]]. Evaluation rules are defined later in this section.
179 2 Florido Paganelli
# At the next group meeting or call, the group decides and merges the -draft files with the official ones.
180 2 Florido Paganelli
¤ If the above is not possible, at least once a year the group meets and does the merge on all documents. This MUST be a scheduled venue.
181 2 Florido Paganelli
182 2 Florido Paganelli
Evaluation rules of thumb
183 2 Florido Paganelli
# Check namespace: if it uses a DNS-style name the requester MUST reasonably justify relating it to that domain, i.e. MUST be either the domain of a relevant project or is it clearly related to a standard service provided by that project. See also [[Enumerations_procedures_and_best_practices_v10#2-Naming-Schemes|Section 2]].
184 2 Florido Paganelli
# Checking that we don't already have something suitable in the existing list.
185 2 Florido Paganelli
# Sanity checking that the value is naming something that matches the conceptual purpose of the enumeration.
186 2 Florido Paganelli
187 2 Florido Paganelli
h2. 5. References
188 2 Florido Paganelli
189 2 Florido Paganelli
* [GFD147]: Sergio Andreozzi et al., GLUE Specification v. 2.0, 2009, http://www.ogf.org/documents/GFD.147.pdf
This is a static archive of the previous Open Grid Forum Redmine content management system saved from host redmine.ogf.org file /projects/glue-wg/wiki/Enumerations_procedures_and_best_practices_v11/annotate/3 at Fri, 04 Nov 2022 15:14:44 GMT