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_v10/annotate/22 at Fri, 04 Nov 2022 15:14:22 GMT GLUE WG - Open Grid Forum

Enumerations procedures and best practices v10

Version 22 (Florido Paganelli, 06/18/2014 06:54 AM)

1 1 Shiraz Memon
{{>toc}}
2 1 Shiraz Memon
3 2 Florido Paganelli
h1. OGF GLUE2 Enumerations procedures and best practices
4 1 Shiraz Memon
5 2 Florido Paganelli
Author: Florido Paganelli florido.paganelli_REMOVE!THIS_@hep.lu.se
6 1 Shiraz Memon
7 2 Florido Paganelli
version:1.0
8 1 Shiraz Memon
9 2 Florido Paganelli
Document Status: Work in Progress
10 1 Shiraz Memon
11 19 Florido Paganelli
Last revision: 2014-06-18
12 1 Shiraz Memon
13 18 Florido Paganelli
h2. 1. Introduction
14 1 Shiraz Memon
15 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.
16 1 Shiraz Memon
17 7 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).
18 1 Shiraz Memon
19 18 Florido Paganelli
h3. 1.1. Acknowledgements
20 1 Shiraz Memon
21 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.
22 1 Shiraz Memon
23 18 Florido Paganelli
h2. 2. Naming Schemes
24 1 Shiraz Memon
25 2 Florido Paganelli
The following rules apply:
26 1 Shiraz Memon
27 20 Florido Paganelli
# Every string is RECOMMENDED to be lowercase.
28 20 Florido Paganelli
# Clients MUST consider these strings case-sensitive as defined in GFD.147.
29 20 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.
30 2 Florido Paganelli
31 19 Florido Paganelli
h3. 2.1. Services
32 2 Florido Paganelli
33 4 Florido Paganelli
This applies to the GLUE2 Open Enumeration @ServiceType_t.@
34 2 Florido Paganelli
35 2 Florido Paganelli
See also GFD.147, Appendix B.31
36 2 Florido Paganelli
37 3 Florido Paganelli
   <pre><organization_name>.<product_name>.<service_detail></pre>
38 2 Florido Paganelli
39 2 Florido Paganelli
where
40 1 Shiraz Memon
41 5 Florido Paganelli
@<organization_name>@ 
42 5 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.
43 1 Shiraz Memon
Presence: *RECOMMENDED* for *new* names. Exceptions MUST be justified.
44 1 Shiraz Memon
45 5 Florido Paganelli
@<product_name>@ 
46 5 Florido Paganelli
free form string for product names
47 1 Shiraz Memon
Presence: *MANDATORY*
48 3 Florido Paganelli
49 5 Florido Paganelli
@<service_detail>@ 
50 5 Florido Paganelli
free form string that SHOULD identify a subservice or a service implementation. It can contain dots.
51 3 Florido Paganelli
Presence: *OPTIONAL*
52 2 Florido Paganelli
53 12 Florido Paganelli
Decision: *RECOMMENDED* requirement is 
54 2 Florido Paganelli
55 3 Florido Paganelli
<pre><organization_name>.<product_name></pre>
56 2 Florido Paganelli
57 3 Florido Paganelli
Examples: @org.nordugrid.arex, org.glite.ce.cream@
58 2 Florido Paganelli
59 2 Florido Paganelli
Existing names not following the above rules can be kept, but MAY be Deprecated to be consistent with recommendations. (see Section 2.4 and Section 4.1)
60 2 Florido Paganelli
61 18 Florido Paganelli
h3. 2.2. Interfaces
62 2 Florido Paganelli
63 8 Florido Paganelli
This applies to the GLUE2 Open Enumeration @InterfaceName_t.@
64 2 Florido Paganelli
GFD.147 Appendix B.18 does not define any clear format. The following is RECOMMENDED:
65 8 Florido Paganelli
<pre><organization_name>.<interface_name></pre>
66 1 Shiraz Memon
67 2 Florido Paganelli
where:
68 1 Shiraz Memon
69 8 Florido Paganelli
@<organization_name>@
70 8 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.
71 8 Florido Paganelli
Presence: *RECOMMENDED* for *new* names. Exceptions MUST be justified.
72 2 Florido Paganelli
73 8 Florido Paganelli
@<interface_name>@
74 1 Shiraz Memon
free form string for product names
75 8 Florido Paganelli
Presence: *MANDATORY*
76 2 Florido Paganelli
77 8 Florido Paganelli
Examples: @org.nordugrid.xbes, org.ogf.glue.emies.activitycreation, org.glite.voms@
78 2 Florido Paganelli
79 20 Florido Paganelli
h3. 2.3. Capabilities
80 2 Florido Paganelli
81 9 Florido Paganelli
See GFD.147, appendix B.5, on @Capability_t@.
82 2 Florido Paganelli
83 18 Florido Paganelli
h3. 2.4. Sorting out special classes of names
84 2 Florido Paganelli
85 10 Florido Paganelli
h4. In case the organization name is unknown/undefined/short-lived 
86 2 Florido Paganelli
87 2 Florido Paganelli
Use the reserved prefix:
88 2 Florido Paganelli
89 2 Florido Paganelli
    org.ogf.glue.
90 2 Florido Paganelli
91 10 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.
92 2 Florido Paganelli
93 10 Florido Paganelli
Example:For EMIR, developed during EMI project that now is over, @ServiceType_t@ is: @org.ogf.glue.emir@
94 2 Florido Paganelli
95 2 Florido Paganelli
If a project ends and the product has an orphaned reverse domain name, the name can be kept.
96 2 Florido Paganelli
97 2 Florido Paganelli
h4. Simplified naming for Services with only one Interface
98 1 Shiraz Memon
99 11 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.@
100 2 Florido Paganelli
101 18 Florido Paganelli
h2. 3. Requesting new Open Enumerations
102 2 Florido Paganelli
103 13 Florido Paganelli
A community willing to submit new open enumeration MUST:
104 13 Florido Paganelli
105 21 Florido Paganelli
# Provide the following information about the enumeration to be submitted:
106 13 Florido Paganelli
** *Type* of the enumeration to be added (i.e. one of the types described in GFD.147, Appendix B )
107 13 Florido Paganelli
** *Name* of the enumeration as in the guidelines in Section 2;
108 13 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.
109 13 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.
110 21 Florido Paganelli
# Send the above information to the OGF group at the address glue-wg@ogf.org with subject “[Enumerations] Request for addition/</nowiki>obsoletion/modification”
111 13 Florido Paganelli
112 13 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.
113 13 Florido Paganelli
114 18 Florido Paganelli
h2. 4. Management of Open Enumerations
115 1 Shiraz Memon
116 14 Florido Paganelli
The group preserves the current list of Open Enumerations in the git repository at the link
117 14 Florido Paganelli
118 14 Florido Paganelli
> https://github.com/OGF-GLUE/Enumerations
119 14 Florido Paganelli
120 14 Florido Paganelli
in the form of CSV files. Section 4.1 contains a description of the content of the CSV files.
121 14 Florido Paganelli
122 14 Florido Paganelli
The groups keeps them updated using the procedures listed in this document, defined in Section 4.3.
123 14 Florido Paganelli
124 18 Florido Paganelli
h3. 4.1. Description of Open Enumerations CSV files
125 14 Florido Paganelli
126 14 Florido Paganelli
CSV filenames in git-hub are of the form:
127 17 Florido Paganelli
128 15 Florido Paganelli
|_.Filename |_.Purpose |_.Example | 
129 14 Florido Paganelli
| @<EnumerationName_t>.csv@ |  Contains Open Enumerations officially approved by the group. | @ServiceType_t.csv@ |
130 14 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@ |
131 2 Florido Paganelli
132 22 Florido Paganelli
Records contained in the CSV files are as follows:
133 22 Florido Paganelli
134 22 Florido Paganelli
|_.Field Name |_.Purpose |_.Example | 
135 22 Florido Paganelli
| EnumerationType | Enumeration Type name. MUST be the same as in the filename. | @ServiceType_t@ |
136 22 Florido Paganelli
| EnumerationValue | It's the enumeration value. | @org.nordugrid.arex@ |
137 22 Florido Paganelli
| Description | Contains the textual description of the object represented by the enumeration name. | @NorduGrid Resource Coupled Execution Service@ |
138 22 Florido Paganelli
| Status | See discussion below. | @Recommended@ |
139 22 Florido Paganelli
| Recommended | If this field is NOT EMPTY, then the contained string SHOULD be used instead of the EnumerationValue. | @org.nordugrid.arex@ |
140 22 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@ |
141 22 Florido Paganelli
142 22 Florido Paganelli
143 22 Florido Paganelli
144 18 Florido Paganelli
h3. 4.2. Statuses
145 2 Florido Paganelli
146 18 Florido Paganelli
h3. 4.3. GLUE2 Working Group Procedures
147 2 Florido Paganelli
148 18 Florido Paganelli
h2. 5. References
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_v10/annotate/22 at Fri, 04 Nov 2022 15:14:22 GMT