Greetings,
I'm looking for feedback on the following proposed design changes/and
or assertions regarding the cfg_cache file. I believe this applies
equally to both pkg(5) clients and the pkg(5) depot, although initial
implementation work will focus on the depot. Much of what is covered
here is intended to suit the recent authority/ operation proposal [0]
and the issues noted in bug 5750 [7].
Format Versioning
=================
Justification
-------------
The configuration file needs to be versioned so that software reading
it can determine the format or semantics of the file.
Implementation Requirements
---------------------------
* Versioning must be implemented such that clients (regardless of
version) can always reliably determine the format version.
* Simple dotsequence semantics must be used (e.g. 1, or 1.2) to
represent the version. The following rules apply:
-- An increment of the first digit will indicate a major,
incompatible change in the configuration information (such as the
removal of a configuration attribute or section).
-- An increment of the second digit will indicate a minor, compatible
change in configuration information (such as the addition of a
configuration attribute or section).
-- The third digit (micro) is reserved and should not be used.
Suggested Implementations
-------------------------
* via configuration attribute in the file
-- advantage: allows maintainers to maintain a consistent
configuration file name regardless of depot software version
-- disadvantage: depot software has to know how to parse the file to
obtain the version
* via file extension (e.g. cfg_cache.1, cfg_cache.1.2, etc.)
-- advantage: allows an easy way to determine configuration version
information without requiring the depot software to be able to know how
to parse a particular version
-- disadvantage: may frustrate depot administrators
Localisation
============
Justification
-------------
Some of the information provided by the depot/repository
administrator(s) is intended for consumption by users and is locale
and/or region specific. Examples might include: repository name,
repository description, point of contact for a specific locale, license
terms, and so on.
Implementation Requirements
---------------------------
* Configuration information should be structured such that every
configuration value can be present in an "all locale/region" with
specific locale and/or region values treated as overrides. This allows
the system to fall-back whenever a more specific value is not available
or applicable.
* Locale/languages should be indicated in the format described by RFC
4646 [1].
* It should be possible to specify a list of accepted languages with
the ability to assign different quality values to each locale so that a
user's language preferences can be respected [2] when working with any
related APIs.
* No changes to related APIs must be required to support new
locales/languages.
Configuration Organisation
==========================
Justification:
To ensure that other design goals can be met, configuration
categorisation must be limited to promote organisation and ease of use.
Sections and keys should be stored in a consistent sort-order for
consistency. Configuration values must be written as provided to
preserve loss of information semantics.
Implementation Requirements
---------------------------
* Categorisation must be limited to a depth of one (i.e. repository
-> name).
* Configuration keys must be limited to a simple, base character set
(e.g. [A-Za-z0-9._-]).
* Configuration data must be structured such that new entries can be
added without negatively impacting older clients when the data changes
(compatibly).
File Format
===========
Justification:
The current file-format used by cfg_cache is fragile since changes in
the format lead to loss of configuration information when re-written by
older clients or unexpected errors. In addition, it has limited
expression for the data structures that much of the pkg(5) relies upon
internally, adding unnecessary overhead and complexity to clients (e.g.
mirrors, locale/language specific information, etc.).
Implementation Requirements
---------------------------
* Must fully support unicode.
* The addition of new information must be possible while still
allowing older software versions to read the portions of the
configuration information it knows about.
* Information added in newer file versions must not be lost when the
configuration information is read and re-written by older software.
* Must be easy for machines and humans (or qualified variations
thereof) to read and write.
* Must allow native expression of common data structures (e.g. dict,
list, int, booleans, etc.) without (reasonable) loss of information
(e.g. whitespace is preserved, but floating point representation may be
lossy).
* Must be able to represent the current set of configuration
information or other information indicated in this document.
Suggested Format
----------------
JSON (JavaScript Object Notation): a lightweight data-interchange
format [3] natively supported by Python (as of version 2.6 via
simplejson). Human readability is subjectively greater than that of
alternative formats when comparing examples of alternatives [4] such as
XML, etc.
The one, known drawback of the JSON format is the lack of support for
comments. This was apparently removed due to disuse.
Python natively supports JSON via the simplejson module [5] (now part of
Python's standard distribution since 2.6) and is available under liberal
licensing terms (MIT license [6]). The simplejson module is also
targeted for integration into build 105 for older versions of Python so
will not require importing the module into our gate.
Implementation Sample
---------------------
{
"configuration": {
"version": "1",
"all": {
"repository": {
"content_mirrors": ["http://mirror-1.example";,
"http://mirror-2.example";],
"description": "This package repository contains useful software.",
"maintainer_email": "[email protected]",
"maintainer_name": "Package Support",
"name": "Package Repository",
},
},
"th": {
"repository": {
"content_mirrors": ["http://mirror-1-th.example";],
"maintainer_email": "[email protected]",
"maintainer_name": "คำถามซอฟต์แวร์",
"name": "เว็บไซต์ซอฟต์แวร์",
},
}
},
}
--
[0] http://markmail.org/message/agnoxwelmj7mvrwr
[1] http://www.ietf.org/rfc/rfc4646.txt
[2] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4
[3] http://www.ietf.org/rfc/rfc4627.txt
[4] http://www.json.org/example.html
[5] http://simplejson.googlecode.com/svn/tags/simplejson-2.0.7/docs/
[6] http://www.opensource.org/licenses/mit-license.php
[7] http://defect.opensolaris.org/bz/show_bug.cgi?id=5750
_______________________________________________
pkg-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
