A description of an XML application which itemizes changes over the life-span of a software project. Changes are tracked by releases, with a granularity of individual items made up of files that were affected. Randy J. Ray <rjray@blackperl.com> 2009-01-01 changelog,xml,schema An XML Schema describing an XML vocabulary for software project change-logs. XML Schema for Changelogs An XML Schema describing an XML vocabulary for software project change-logs. Randy J. Ray Randy J. Ray The versionString type is applied to attributes that describe simple revision-number strings. It only supports dotted-decimal styled version numbers. An informationType is an open-ended container type that allows mixed-content which can include elements from other XML namespaces. This allows users to include Dublin Core metadata, XHTML tags, etc. as desired within the <description> and similar blocks. It also allows for open-ended extension of ChangeLogML with things such as source-control specification, etc. The source attribute, if present, is used to refer to any external resource that may be related to the contents of the block-element that has the attribute. The role or relevance of the reference is not specified or constrained. The value of the attribute must be a URI, but may be absolute, relative, or a reference to a fragment. The only restriction is that it be a valid URI. A descriptionType extends informationType to add a specific attribute, called "lang", that specifies the (human) language the text of the block is written in. This allows for a ChangeLog to have multiple versions of the same <description> block in differing languages, leaving it to processors of the document to choose which one to display. This attribute specifies the language in which the content of the <description> block is written. The value of the attribute should be a language code (generally two characters, possibly followed by an underscore and qualifying country-code when the language is used by several countries), and the default value is "en_US" (American English). The fileType definition is used for the <file> element, a part of the changeType declaration. It is defined separately so that it can be referred to from multiple places. The <description> block is optional, and may occur multiple times in different languages (as with all instances of this tag). It is used to describe the function or role of the file, and would generally only be used the first time a file is introduced. This block is optional, and may occur only once. If present, it is used to introduce source-control information specific to the current file. This can be useful if some elements of the project are spread across different source-control systems. This attribute provides the path-name of the file. In general, this will be a path that is relative to the base directory of the project itself, though there is no rule prohibiting absolute paths, or presuming that paths are relative to some other location. An optional attribute, this indicates the revision, or version, of the file as it is being referred to in the current context. Some source-control systems (such as CVS) version files individually, while others (such as Subversion) version files in groups generally referred to as transactions. An optional attribute, this allows specification of the author of the current revision of the file being described. This attribute describes what the change to this file represents. The value is restricted to one of the strings: ADD, CHANGE, DELETE, MOVE or RESTORE. The default value is CHANGE, which simply means the file was modified. The other labels represent the states at which a file was added to the project, deleted from the project, moved within the file-system, or restored from a deleted state. A file element describes one changed file as part of a containing <change> or <fileset> element. This uniqueness-constraint ensures that only one <description> tag with a given value for the "lang" attribute occurs within the enclosing <file>. Note that "lang" defaults to "en_US". The changeType declaration is used to define the structure of the <change> blocks. Each such block describes a single change to the project; this change may affect only one file, or it may affect many files. What each change has in common, is that it requires the specification of one or more affected files, as well as a description of the change itself. For specifying the files affected by the change, the document may use one of two options: <file> or <fileset>. If the change affects only one file, a single <file> may be used. Otherwise, multiple files must be contained within an enclosing <fileset>. A <fileset> containing exactly one <file> tag should be considered functionally equivalent to just the stand-alone <file> tag itself. When the change affects just one file, this element is used to specify and describe that file. A <fileset> is a container for one or more <file> tags, though it is more efficient to use a single <file> element if there is only one changed file. All files in the container are considered to be part of the same change, and in terms of source-control are regarded as having been committed to the repository at the same time. This block is optional, and may occur only once. If present, it is used to introduce source-control information specific to the fileset/change. As some source-control systems (such as Subversion) handle groups of changed files as a single transaction, it may be more economical to specify source-control information at this level rather than for each file within the child-element <fileset> individually. One or more <file> elements must be present, with no limit on the number allowed. The structure of the block is the same at this level as for a single, stand-alone instance of <file>. A <fileset> may specify a single revision which applies to all files in the contained <file> elements. Within the <change> block, a <description> element represents the description of the change, in a manner similar to the comments provided to source-control systems when files are committed. An optional attribute, this allows specification of the author of the current change-set being described. This is useful if the whole of a change is credited to one committer, as opposed to specifying the same author for every file in the <fileset> block. The "date" attribute details when the change was submitted, committed to version-control, etc. It uses the "dateTime" data-format as defined by the XML Schema standard, which is the ISO 8601 format for dates and times. Although ISO 8601 allows strings that specify only the date or time portions, the value of this attribute must contain at least the date, if not a full specification. A changeType instance may specify a unique ID by which it can be referred to from external documents. The value of this attribute must be unique across all "id" attributes in the document, and must conform to the XML Schema definition of an identifier token. A change element defines one change within a release. The change itself may cover several files, but the single description within the change applies to all files referenced within. This uniqueness-constraint ensures that only one <description> tag with a given value for the "lang" attribute occurs within the enclosing <change>. Note that "lang" defaults to "en_US". The releaseType is the primary piece of information that a ChangeLogML file collects and organizes. A release contains an optional description and other informational blocks, followed by one or more change blocks. The release element is also the greatest user of attributes besides the file element. A releaseType instance must have at least a "version" attribute, uniquely identifying the release itself. Additionally, it must have a "date" attribute to specify the date the release was created. The <description> element in a release describes the release as a whole, acting as a summary of the release itself. The <information> element is a container which may be used to provide meta-data such as Dublin Core, etc., that is more specific to the release than any general meta-data provided in the <changelog> element's <information> container. The <source-control> element for a release acts as a container for information on source-control that is specific to the release, more specific than information contained within any <source-control> block for the <changelog> element. The <change> element is an instance of the type, "changeType". One or more of these blocks must be present in a <release> block. There is no upper-limit to the number of <change> blocks allowed. The "version" attribute represents the version by which the release of the project is represented. It should be unique, though it is not treated in the same way as the "id" attribute; uniqueness is managed as a function of the schema rather than the definition of the type of data it can contain. It is not restricted to numerals and periods, as file revision-numbers are. The "date" attribute details when the release was made available, bundled, etc. It uses the "dateTime" data-format as defined by the XML Schema standard, which is the ISO 8601 format for dates and times. Although ISO 8601 allows strings that specify only the date or time portions, the value of this attribute must contain at least the date, if not a full specification. A releaseType instance may specify a unique ID by which it can be referred to from external documents. The value of this attribute must be unique across all "id" attributes in the document, and must conform to the XML Schema definition of an identifier token. The release element details one release within the overall change-log itself. Because the release element has a required attribute that provides a time-stamp, releases may appear in any order within the change-log, since processors can sort the elements by their relative dates. This uniqueness-constraint ensures that only one <description> tag with a given value for the "lang" attribute occurs within the enclosing <release>. Note that "lang" defaults to "en_US". The subprojectType is a way of allowing a project to express relationship to one or more sub-projects within itself, such that the sub-projects are able to have their own changelogs and release schedules. An instance of subprojectType may explicitly contain <release> blocks (that may or may not simply be replicated from the sub-project's own ChangeLogML), or it may use a facility such as XInclude (or m4 pre-processed, etc.) to dynamically include such blocks from the sub-project. The <description> block for a subprojectType instance is used to provide a summary of the sub-project, like an abstract or overview for an article. The <information> block is an open-ended container that allows content from other XML namespaces to be included, for such things as Dublin Core Metadata, Creative Commons information, etc. Like the previous, the <source-control> block is an open-ended container for the inclusion of content from additional namespaces. However, this container is intended to be specifically used for information on the source-control system employed by the project. Lastly, the subprojectType instance will contain zero or more <release> blocks. Ideally these will occur in order, either ascending or descending, of the dates of the given releases. This is optional, since any processor will be capable of sorting the blocks on their "date" attributes. A subprojectType instance may specify a unique ID by which it can be referred to from external documents. The value of this attribute must be unique across all "id" attributes in the document, and must conform to the XML Schema definition of an identifier token. An required attribute, this specifies the name of the sub-project. A schema-level constraint is used to ensure that names are unique between instances of subprojectType. The subproject element sets up a child-project that is considered part of the main project, but which may release on its own, separate schedule. The parent project may replicate the child's release history into its own ChangeLogML file, or it may use XInclude elements to import it. This uniqueness-constraint ensures that only one <description> tag with a given value for the "lang" attribute occurs within the enclosing <subproject>. Note that "lang" defaults to "en_US". An instance of changelogType will generally be the root-level element in a ChangeLogML document. It contains the project-level information such as name, summary, etc. as well as acting as a container for the <release> blocks that actually iterate the project's change history. This is the name of the project that this changelog covers. This is the title for the project, a sort of longer "name" that can be used for web pages, etc. The <description> block for a changelogType instance is used to provide a summary of the project, like an abstract or overview for an article. The <information> block is an open-ended container that allows content from other XML namespaces to be included, for such things as Dublin Core Metadata, Creative Commons information, etc. Like the previous, the <source-control> block is an open-ended container for the inclusion of content from additional namespaces. However, this container is intended to be specifically used for information on the source-control system employed by the project. The changelogType instance will contain zero or more <release> blocks. Ideally these will occur in order, either ascending or descending, of the dates of the given releases. This is optional, since any processor will be capable of sorting the blocks on their "date" attributes. Lastly, the changelogType instance may contain zero or more <subproject> blocks. These blocks provide information on sub-projects of the main project, and are distinguished by a unique "name" attribute on each block. These elements may be null, since there is no requirement that a sub-project have any releases before the parent project does. A changelogType instance may specify a unique ID by which it can be referred to from external documents. The value of this attribute must be unique across all "id" attributes in the document, and must conform to the XML Schema definition of an identifier token. The changelog element is intended as the document root element. It contains descriptive elements (<description>, <source-control>, etc.) and one or more release blocks. This uniqueness-constraint ensures that only one <description> tag with a given value for the "lang" attribute occurs within the enclosing <changelog>. Note that "lang" defaults to "en_US". This key-constraint ensures that each <release> block has a distinct and unique "version" attribute. This key-constraint ensures that each <subproject> block has a distinct and unique "name" attribute.