Shawn Walker wrote:
> 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
Are there any more comments on this?
Thanks,
--
Shawn Walker
_______________________________________________
pkg-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
