-
Notifications
You must be signed in to change notification settings - Fork 7
/
README.txt
193 lines (141 loc) · 6.65 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
###############################################################################
# GLUE2 Open Enumerations Registry
# URL: http://redmine.ogf.org/projects/glue-wg
# Maintainer: Florido Paganelli [email protected]
# Last update: 2014-05-02
###############################################################################
***********************************************************
Procedures and best practices regarding Open Enumerations
are still under discussion within the group.
A proposal is here:
http://redmine.ogf.org/dmsf_files/13224?download=
***********************************************************
§ Table of Contents
1. Version History
2. Release Notes
3. Document conventions
4. What are Open Enumerations
5. How to add new enumerations
6. Documents in 'draft' status
7. Structure of the CSV files
8. Merging documents into one
+++++++++++++++++++++++++++
§ 1. Version History
+++++++++++++++++++++++++++
This document:
v0.4 - Release 1.0: Added Document conventions, Release Notes
and sections 7-8.
v0.3 - Linked document with updated information. 2014-04-04
v0.2 - Updated rules for 'draft' documents. 2013-06-14
v0.1 - Initial release. 2012-12-07
For version history of the whole set of Enumerations documents,
please refer to ChangeLog.txt
+++++++++++++++++++++++++++
§ 2. Release Notes
+++++++++++++++++++++++++++
With Release 1.0 a new CSV file structure is introduced, to ease two
tasks:
1) Find out which Recommended Open Enumeration is to be used instead
of a Deprecated one
2) Merge all document files into one
A description of the new file structure is given in this document.
This release introduces a merge script that allows information consumers
to have all enumerations in one single CSV file. Usage is also described
in this document.
The initial release 1.0 introduces no new enumerations. Minor releases
might add new values.
++++++++++++++++++++++++++++++++
§ 3. Document conventions
++++++++++++++++++++++++++++++++
The following terminology is adopted:
Information/service provider
software that produces the GLUE2 entries.
Information consumer
software or person that reads some GLUE2 information source.
Additionally the following holds:
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).
++++++++++++++++++++++++++++++++
§ 4. What are Open Enumerations
++++++++++++++++++++++++++++++++
Open Enumerations as defined in the GLUE2 Model document:
[1] http://www.ogf.org/documents/GFD.147.pdf
are special strings that are used to identify technologies and features
in the GLUE2 world. Each open enumeration must be lowercase and
must come with a description.
GLUE2 model defines some of them in Appendix B. In this repository,
the GLUE2 WG will maintain all those that are added by who wants
to use the GLUE2 model, so that they can be used for validation.
In a first release, these open enumerations will be presented in the
CSV (Comma Separated Values) format, but more elaborated formats might
follow upon request.
+++++++++++++++++++++++++++++++++
§ 5. How to add new enumerations
+++++++++++++++++++++++++++++++++
For the moment being, just write an email to the GLUE2 WG at:
http://redmine.ogf.org/projects/glue-wg
Or email the maintainer indicated in the header of this document.
Send the list of Open Enumerations provided by a description for
each entry, and a reference to the organization that forged them.
Each enumeration string has his own format, please refer to [1] to know
what format to use. At the moment this is still work in progress.
+++++++++++++++++++++++++++++++++
§ 6. Documents in 'draft' status
+++++++++++++++++++++++++++++++++
Some of the GLUE2 CSV documents are named
<type>-draft.csv
Example: Capability_t-draft.csv
Such documents contain strings whose status has not yet been
approved/revised by the GLUE2 Working Group. They can be used by
consumers, but they are subject to change.
Some of the strings in such documents MUST be considered valid but not
official.
+++++++++++++++++++++++++++++++++
§ 7. Structure of the CSV files
+++++++++++++++++++++++++++++++++
The CSV file header is as follows:
| EnumerationType | EnumerationValue | Description | Status | Recommended | Deprecates |
Each column has the following content/meaning:
EnumerationType: the type name as described in GFD.147.
i.e. ServiceType_t
EnumerationValue: A string that is the enumeration itself. This string
should be used by information providers and consumers to be
published in information systems.
Status: Tell wheter the string should be used or not. Can be one of:
Recommended: The EnumerationValue string should be used in
production systems by both service providers and
consumers.
Deprecated: The EnumerationValue string should not be used anymore,
but is still used in production systems. Information
providers are advised to change to the value present in
the "Recommended" column.
Information consumers should temporarily accept or
expect both the Deprecated and the Recommended strings.
Obsolete: The string, and possibly the related represented entity,
are not used in production anymore and should not be
published bu providers or accepted by consumers. This
is mainly used for historical record.
Recommended: If this field is NOT EMPTY, then the contained string
SHOULD be used instead of the EnumerationValue.
Read description of the Status field for more details.
Deprecates: If the field is NOT EMPTY, then the EnumerationValue string
SHOULD be used instead of the contained values.
+++++++++++++++++++++++++++++++++
§ 8. Merging documents into one
+++++++++++++++++++++++++++++++++
To obtain a single document containing all enumeration, execute the
following bash script in the GLUE2 Enumerations git repository
directory:
./mergeEnums.sh
The result will be two documents:
GLUE2OpenEnumerations.csv
Contains all officially approved GLUE2 Open Enumerations
GLUE2OpenEnumerations-drafts.csv
Contains all GLUE2 Open Enumerations documents pending approval.
Note that those Enumerations that are pending approval have no
"Status": information validators might fire a warning if a consumer
is using an enumeration in draft state.
Those documents are a simple "cat" of the other documents but with
a single header for ease of import.