Enumerations procedures and best practices v11
Version 3 (Florido Paganelli, 06/18/2014 08:31 AM) → Version 4/5 (Shiraz Memon, 04/10/2015 10:34 AM)
{{>toc}}
| *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 |
h1. OGF GLUE2 Enumerations procedures and best practices
Author: Florido Paganelli florido.paganelli_REMOVE!THIS_@hep.lu.se
version:1.1rc0
Document Status: Draft
Last revision: 2014-06-18
h2. 1. Introduction
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.
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).
h3. 1.1. Acknowledgements
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.
h2. 2. Naming Schemes
The following rules apply:
# Every string is RECOMMENDED to be lowercase.
# Clients MUST consider these strings case-sensitive as defined in "GFD.147":http://www.ogf.org/documents/GFD.147.pdf.
# Case MUST NOT be used as a way to distinguish strings; in practice, the group will not accept names that only differ in case.
h3. 2.1. Services
This applies to the GLUE2 Open Enumeration @ServiceType_t.@
See also "GFD.147":http://www.ogf.org/documents/GFD.147.pdf, Appendix B.31
<pre><organization_name>.<product_name>.<service_detail></pre>
where
@<organization_name>@
is the reversed domain name of the organization which provides or maintains the service or a reversed domain name associated with the project.
Presence: *RECOMMENDED* for *new* names. Exceptions MUST be justified.
@<product_name>@
free form string for product names
Presence: *MANDATORY*
@<service_detail>@
free form string that SHOULD identify a subservice or a service implementation. It can contain dots.
Presence: *OPTIONAL*
Decision: *RECOMMENDED* requirement is
<pre><organization_name>.<product_name></pre>
Examples: @org.nordugrid.arex, org.glite.ce.cream@
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]])
h3. 2.2. Interfaces
This applies to the GLUE2 Open Enumeration @InterfaceName_t.@
GFD.147 Appendix B.18 does not define any clear format. The following is RECOMMENDED:
<pre><organization_name>.<interface_name></pre>
where:
@<organization_name>@
is the reversed domain name of the organization which provides or maintains the service or a reversed domain name associated with the project.
Presence: *RECOMMENDED* for *new* names. Exceptions MUST be justified.
@<interface_name>@
free form string for product names
Presence: *MANDATORY*
Examples: @org.nordugrid.xbes, org.ogf.glue.emies.activitycreation, org.glite.voms@
h3. 2.3. Capabilities
See "GFD.147":http://www.ogf.org/documents/GFD.147.pdf , appendix B.5, on @Capability_t@.
h3. 2.4. Sorting out special classes of names
h4. In case the organization name is unknown/undefined/short-lived
Use the reserved prefix:
org.ogf.glue.
@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.
Example:For EMIR, developed during EMI project that now is over, @ServiceType_t@ is: @org.ogf.glue.emir@
If a project ends and the product has an orphaned reverse domain name, the name can be kept.
h4. Simplified naming for Services with only one Interface
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.@
h2. 3. Requesting new Open Enumerations
A community willing to submit new open enumeration MUST:
# Provide the following information about the enumeration to be submitted:
** *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 )
** *Name* of the enumeration as in the guidelines in [[Enumerations_procedures_and_best_practices_v10#2-Naming-Schemes|Section 2]];
** *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.
** *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.
# Send the above information to the OGF group at the address glue-wg@ogf.org with subject @“[Enumerations] Request for addition/obsoletion/modification”@
*NOTE:* Requests that are missing the information listed in 1 will be automatically rejected. The proposer will be asked to provide missing information.
h2. 4. Management of Open Enumerations
The group preserves the current list of Open Enumerations in the git repository at the link
bq. https://github.com/OGF-GLUE/Enumerations
in the form of CSV files. Section 4.1 contains a description of the content of the CSV files.
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]].
h3. 4.1. Description of Open Enumerations CSV files
CSV filenames in git-hub are of the form:
|_.Filename |_.Purpose |_.Example |
| @<EnumerationName_t>.csv@ | Contains Open Enumerations officially approved by the group. | @ServiceType_t.csv@ |
| @<EnumerationName_t>-draft.csv@ | Contains Open Enumerations approved by the group AND Open Enumerations pending approval from the group | @ServiceType_t-draft.csv@ |
Records contained in the CSV files are as follows:
# The first row always contain the following strings:
>> @EnumerationType,EnumerationValue,Description,Status,Recommended, Deprecated@
# Rows from the second on contains the following:
|_.Field Name |_.Purpose |_.Example |
| @EnumerationType@ | Enumeration Type name. MUST be the same as in the filename. | @ServiceType_t@ |
| @EnumerationValue@ | It's the enumeration value. | @org.nordugrid.arex@ |
| @Description@ | Contains the textual description of the object represented by the enumeration name. | @NorduGrid Resource Coupled Execution Service@ |
| @Status@ | See discussion below. | @Recommended@ |
| @Recommended@ | If this field is NOT EMPTY, then the contained string SHOULD be used instead of the EnumerationValue. | @org.nordugrid.arex@ |
| @Deprecates@ | If the field is NOT EMPTY, then the EnumerationValue string SHOULD be used instead of the contained values. | @org.nordugrid.execution.arex@ |
h3. 4.2. Statuses
*Terminology:*
*Information/service provider* = software that produces the GLUE2 entries.
*Information consumers* = software that reads some GLUE2 information source.
*Description of Statuses*
*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 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.
Status might contain multiple values, represented as multilined fields in the CSV.
Status MUST NOT be both Recommended and Deprecated. The only allowed combinations are:
*Recommended Obsolete*: The EnumerationValue string is valid but the type is not in use anymore. Equivalent to Obsolete.
*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.
h3. 4.3. GLUE2 Working Group Procedures
# 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).
These values will have no value in the Status column inside the -draft.csv document.
# Promptly upon arrival the group decides about the feasibility of adding the values.
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.
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.
# At the next group meeting or call, the group decides and merges the -draft files with the official ones.
¤ 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.
# Requesting your changes on Github
1 Fork the GLUE 2.0 Enumerations repository from https://github.com/OGF-GLUE/Enumerations.git
2 Update your changes in the csv document(s)
3 Register a "Pull Request"
Evaluation rules of thumb
# 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]].
# Checking that we don't already have something suitable in the existing list.
# Sanity checking that the value is naming something that matches the conceptual purpose of the enumeration.
h2. 5. References
* [GFD147]: Sergio Andreozzi et al., GLUE Specification v. 2.0, 2009, http://www.ogf.org/documents/GFD.147.pdf
| *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 |
h1. OGF GLUE2 Enumerations procedures and best practices
Author: Florido Paganelli florido.paganelli_REMOVE!THIS_@hep.lu.se
version:1.1rc0
Document Status: Draft
Last revision: 2014-06-18
h2. 1. Introduction
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.
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).
h3. 1.1. Acknowledgements
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.
h2. 2. Naming Schemes
The following rules apply:
# Every string is RECOMMENDED to be lowercase.
# Clients MUST consider these strings case-sensitive as defined in "GFD.147":http://www.ogf.org/documents/GFD.147.pdf.
# Case MUST NOT be used as a way to distinguish strings; in practice, the group will not accept names that only differ in case.
h3. 2.1. Services
This applies to the GLUE2 Open Enumeration @ServiceType_t.@
See also "GFD.147":http://www.ogf.org/documents/GFD.147.pdf, Appendix B.31
<pre><organization_name>.<product_name>.<service_detail></pre>
where
@<organization_name>@
is the reversed domain name of the organization which provides or maintains the service or a reversed domain name associated with the project.
Presence: *RECOMMENDED* for *new* names. Exceptions MUST be justified.
@<product_name>@
free form string for product names
Presence: *MANDATORY*
@<service_detail>@
free form string that SHOULD identify a subservice or a service implementation. It can contain dots.
Presence: *OPTIONAL*
Decision: *RECOMMENDED* requirement is
<pre><organization_name>.<product_name></pre>
Examples: @org.nordugrid.arex, org.glite.ce.cream@
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]])
h3. 2.2. Interfaces
This applies to the GLUE2 Open Enumeration @InterfaceName_t.@
GFD.147 Appendix B.18 does not define any clear format. The following is RECOMMENDED:
<pre><organization_name>.<interface_name></pre>
where:
@<organization_name>@
is the reversed domain name of the organization which provides or maintains the service or a reversed domain name associated with the project.
Presence: *RECOMMENDED* for *new* names. Exceptions MUST be justified.
@<interface_name>@
free form string for product names
Presence: *MANDATORY*
Examples: @org.nordugrid.xbes, org.ogf.glue.emies.activitycreation, org.glite.voms@
h3. 2.3. Capabilities
See "GFD.147":http://www.ogf.org/documents/GFD.147.pdf , appendix B.5, on @Capability_t@.
h3. 2.4. Sorting out special classes of names
h4. In case the organization name is unknown/undefined/short-lived
Use the reserved prefix:
org.ogf.glue.
@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.
Example:For EMIR, developed during EMI project that now is over, @ServiceType_t@ is: @org.ogf.glue.emir@
If a project ends and the product has an orphaned reverse domain name, the name can be kept.
h4. Simplified naming for Services with only one Interface
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.@
h2. 3. Requesting new Open Enumerations
A community willing to submit new open enumeration MUST:
# Provide the following information about the enumeration to be submitted:
** *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 )
** *Name* of the enumeration as in the guidelines in [[Enumerations_procedures_and_best_practices_v10#2-Naming-Schemes|Section 2]];
** *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.
** *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.
# Send the above information to the OGF group at the address glue-wg@ogf.org with subject @“[Enumerations] Request for addition/obsoletion/modification”@
*NOTE:* Requests that are missing the information listed in 1 will be automatically rejected. The proposer will be asked to provide missing information.
h2. 4. Management of Open Enumerations
The group preserves the current list of Open Enumerations in the git repository at the link
bq. https://github.com/OGF-GLUE/Enumerations
in the form of CSV files. Section 4.1 contains a description of the content of the CSV files.
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]].
h3. 4.1. Description of Open Enumerations CSV files
CSV filenames in git-hub are of the form:
|_.Filename |_.Purpose |_.Example |
| @<EnumerationName_t>.csv@ | Contains Open Enumerations officially approved by the group. | @ServiceType_t.csv@ |
| @<EnumerationName_t>-draft.csv@ | Contains Open Enumerations approved by the group AND Open Enumerations pending approval from the group | @ServiceType_t-draft.csv@ |
Records contained in the CSV files are as follows:
# The first row always contain the following strings:
>> @EnumerationType,EnumerationValue,Description,Status,Recommended, Deprecated@
# Rows from the second on contains the following:
|_.Field Name |_.Purpose |_.Example |
| @EnumerationType@ | Enumeration Type name. MUST be the same as in the filename. | @ServiceType_t@ |
| @EnumerationValue@ | It's the enumeration value. | @org.nordugrid.arex@ |
| @Description@ | Contains the textual description of the object represented by the enumeration name. | @NorduGrid Resource Coupled Execution Service@ |
| @Status@ | See discussion below. | @Recommended@ |
| @Recommended@ | If this field is NOT EMPTY, then the contained string SHOULD be used instead of the EnumerationValue. | @org.nordugrid.arex@ |
| @Deprecates@ | If the field is NOT EMPTY, then the EnumerationValue string SHOULD be used instead of the contained values. | @org.nordugrid.execution.arex@ |
h3. 4.2. Statuses
*Terminology:*
*Information/service provider* = software that produces the GLUE2 entries.
*Information consumers* = software that reads some GLUE2 information source.
*Description of Statuses*
*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 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.
Status might contain multiple values, represented as multilined fields in the CSV.
Status MUST NOT be both Recommended and Deprecated. The only allowed combinations are:
*Recommended Obsolete*: The EnumerationValue string is valid but the type is not in use anymore. Equivalent to Obsolete.
*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.
h3. 4.3. GLUE2 Working Group Procedures
# 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).
These values will have no value in the Status column inside the -draft.csv document.
# Promptly upon arrival the group decides about the feasibility of adding the values.
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.
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.
# At the next group meeting or call, the group decides and merges the -draft files with the official ones.
¤ 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.
# Requesting your changes on Github
1 Fork the GLUE 2.0 Enumerations repository from https://github.com/OGF-GLUE/Enumerations.git
2 Update your changes in the csv document(s)
3 Register a "Pull Request"
Evaluation rules of thumb
# 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]].
# Checking that we don't already have something suitable in the existing list.
# Sanity checking that the value is naming something that matches the conceptual purpose of the enumeration.
h2. 5. References
* [GFD147]: Sergio Andreozzi et al., GLUE Specification v. 2.0, 2009, http://www.ogf.org/documents/GFD.147.pdf