Stage 3 proposal: Feature #13102 (Release Management Domain)

Transcription

1 Stage 3 proposal: Feature #13102 (Release Management Domain)

2 Contents 2 Contents Stage 3 proposal: Feature #13102 (Release Management Domain)... 3 Structural implementation...3 Listing: releasemanagement.dtd... 4 Listing: releasemanagementdomain.ent... 8 Listing: releasemanagementdomain.mod... 8 Specification documentation...13 Changes to the architectural specification...13 Changes to the language specification... 15

3 Stage 3 proposal: Feature #13102 (Release Management Domain) 3 Stage 3 proposal: Feature #13102 (Release Management Domain) This proposal defines a release management domain for DITA 1.3 that enables content workers to log comments and metadata at the topic level when changes are made. The model for this domain comes from bookmap s <bookchangehistory, with modifications. This proposal seeks to add elements only; no processing is requested. Champion Tom Cihak (tom.cihak@freescale.com) is champion of this proposal, on behalf of the Technical Communications Subcommittee. Tracking information Event Date Links Stage 1 proposal accepted Feb 21, 2012 Minutes from 21 Feb 2012 Stage 2 proposal submitted Aug 23, 2013 Sep 4, 2013 Stage 2 proposal discussed Aug 20, 2013 Aug 27, 2013 Sep 3, 2013 DITA HTML download.php/50445/minutes txt download.php/50502/minutes txt download.php/50570/minutes txt Stage 2 proposal approved Sep 10, download.php/50716/minutes txt Stage 3 proposal submitted to reviewers Include s of reviewers Stage 3 proposal (this document) submitted Approved technical requirements As presented in the stage 2 proposal, this domain is to be implemented as elements only; no processing is requested. All DTD changes are detailed later in this document. Dependencies or interrelated proposals None, though any proposed changes to the content model of <data would have an impact on these elements. Structural implementation This proposal introduces a new release management domain. The top-level domain element is specialized from <metadata; therefore, it can only be included where that element is permissible. The intent is to include the domain within <prolog. Listings of the DTD and its two supporting entity files follow. Corresponding XML Schema files will also be required.

4 Stage 3 proposal: Feature #13102 (Release Management Domain) 4 Listing: releasemanagement.dtd <?xml version="1.0" encoding="utf-8"? <!-- HEADER -- <!-- MODULE: DITA Topic with release management domain integrated -- <!-- VERSION: <!-- DATE: August, <!-- -- <!-- PUBLIC DOCUMENT TYPE DEFINITION -- <!-- TYPICAL INVOCATION -- <!-- -- <!-- Refer to this file by the following public identifier or an appropriate system identifier -- <!-- The public ID above refers to the latest version of this DTD. To refer to this specific version, you may use this value: PUBLIC "-//OASIS//DTD DITA 1.2 Topic//EN" -- <!-- SYSTEM: Darwin Information Typing Architecture (DITA) -- <!-- -- <!-- PURPOSE: DTD to describe DITA Topics -- <!-- -- <!-- ORIGINAL CREATION DATE: -- <!-- March <!-- -- <!-- (C) Copyright OASIS Open 2005, <!-- (C) Copyright IBM Corporation 2001, <!-- All Rights Reserved. -- <!-- -- <!-- UPDATES: -- <! RDA: Added indexing domain -- <! RDA: Added props attribute extensions -- <! EK: Reformatted DTD modules for DITA <! RDA: Modify imbeds to use specific 1.2 version -- <! RDA: Added hazard domain -- <!-- TOPIC ENTITY DECLARATIONS -- <!-- DOMAIN ENTITY DECLARATIONS -- <!ENTITY % relmgmt-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.3 Release Management Domain//EN" "../org.oasis-open.release-management.doctypes/dtd/ releasemanagementdomain.ent" %relmgmt-d-dec; <!ENTITY % hi-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Highlight Domain//EN"

5 Stage 3 proposal: Feature #13102 (Release Management Domain) 5 "../../base/dtd/highlightdomain.ent" %hi-d-dec; <!ENTITY % ut-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Utilities Domain//EN" "../../base/dtd/utilitiesdomain.ent" %ut-d-dec; <!ENTITY % indexing-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Indexing Domain//EN" "../../base/dtd/indexingdomain.ent" %indexing-d-dec; <!ENTITY % hazard-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Hazard Statement Domain//EN" "../../base/dtd/hazardstatementdomain.ent" %hazard-d-dec; <!ENTITY % abbrev-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Abbreviated Form Domain//EN" "abbreviatedomain.ent" %abbrev-d-dec; <!ENTITY % pr-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Programming Domain//EN" "programmingdomain.ent" %pr-d-dec; <!ENTITY % sw-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 Software Domain//EN" "softwaredomain.ent" %sw-d-dec; <!ENTITY % ui-d-dec PUBLIC "-//OASIS//ENTITIES DITA 1.2 User Interface Domain//EN" "uidomain.ent" %ui-d-dec; <!-- DOMAIN ATTRIBUTE DECLARATIONS -- <!-- DOMAIN EXTENSIONS -- <!-- One for each extended base element, with the of the domain(s) in which the extension was declared -- <!ENTITY % pre "pre %pr-d-pre; %sw-d-pre; %ui-d-pre; " <!ENTITY % keyword "keyword %pr-d-keyword; %sw-d-keyword; %ui-d-keyword;

6 Stage 3 proposal: Feature #13102 (Release Management Domain) 6 " <!ENTITY % ph "ph %hi-d-ph; %pr-d-ph; %sw-d-ph; %ui-d-ph; " <!ENTITY % term "term %abbrev-d-term; " <!ENTITY % fig "fig %pr-d-fig; %ut-d-fig; " <!ENTITY % dl "dl %pr-d-dl; " <!ENTITY % index-base "index-base %indexing-d-index-base; " <!ENTITY % note "note %hazard-d-note; " <!ENTITY % metadata "metadata %relmgmt-d-metadata; " <!-- DOMAIN ATTRIBUTE EXTENSIONS -- <!ENTITY % props-attribute-extensions "" <!ENTITY % base-attribute-extensions "" <!-- TOPIC NESTING OVERRIDE -- <!-- Redefine the infotype entity to exclude other topic types and disallow nesting -- <!ENTITY % topic-info-types "topic " <!-- DOMAINS ATTRIBUTE OVERRIDE -- <!-- Must be declared ahead of the DTDs, which first in order -- <!ENTITY included-domains "&hi-d-att; &ut-d-att; &indexing-d-att; &hazard-d-att; &abbrev-d-att; &pr-d-att; &sw-d-att;

7 Stage 3 proposal: Feature #13102 (Release Management Domain) 7 " &ui-d-att; &relmgmt-d-att; <!-- TOPIC ELEMENT INTEGRATION -- <!-- Embed topic to get generic elements -- <!ENTITY % topic-type PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Topic//EN" "../../base/dtd/topic.mod" %topic-type; <!-- DOMAIN ELEMENT INTEGRATION -- <!ENTITY % relmgmt-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.3 Release Management Domain//EN" "../org.oasis-open.release-management.doctypes/dtd/ releasemanagementdomain.mod" %relmgmt-d-def; <!ENTITY % hi-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Highlight Domain//EN" "../../base/dtd/highlightdomain.mod" %hi-d-def; <!ENTITY % ut-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Utilities Domain//EN" "../../base/dtd/utilitiesdomain.mod" %ut-d-def; <!ENTITY % indexing-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Indexing Domain//EN" "../../base/dtd/indexingdomain.mod" %indexing-d-def; <!ENTITY % hazard-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Hazard Statement Domain//EN" "../../base/dtd/hazardstatementdomain.mod" %hazard-d-def; <!ENTITY % abbrev-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Abbreviated Form Domain//EN" "abbreviatedomain.mod" %abbrev-d-def; <!ENTITY % ui-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 User Interface Domain//EN" "uidomain.mod" %ui-d-def; <!ENTITY % pr-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Programming Domain//EN"

8 Stage 3 proposal: Feature #13102 (Release Management Domain) 8 "programmingdomain.mod" %pr-d-def; <!ENTITY % sw-d-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Software Domain//EN" "softwaredomain.mod" %sw-d-def; <!-- ================== End DITA Topic DTD ====================== -- Listing: releasemanagementdomain.ent <?xml version="1.0" encoding="utf-8"? <!-- ============================================================= DITA Release Management Metadata Domain Defines element types for capturing change details within topics or maps. DITA 1.3 Copyright (c) 2013 OASIS Open ============================================================= -- <!-- Release Management DOMAIN ENTITIES -- <!ENTITY % relmgmt-d-metadata "change-historylist " <!ENTITY relmgmt-d-att "(topic relmgmt-d)" <!-- ================== End Highlight Domain Entities ============ -- Listing: releasemanagementdomain.mod <!-- ============================================================= DITA Release Management Metadata Domain Defines element types for capturing change details within topics or maps. DITA 1.3 Copyright (c) 2013 OASIS Open ============================================================= -- <!ENTITY % change-historylist "change-historylist" <!ENTITY % change-item "change-item" <!ENTITY % change-person "change-person" <!ENTITY % change-organization "change-organization" <!ENTITY % change-revisionid "change-revisionid"

9 Stage 3 proposal: Feature #13102 (Release Management Domain) 9 <!ENTITY % change-request-reference "change-request-reference" <!ENTITY % change-started "change-started" <!ENTITY % change-completed "change-completed" <!ENTITY % change-summary "change-summary" <!ENTITY % change-request-system "change-request-system" <!ENTITY % change-request-id "change-request-id" <!-- Long Name: Change History List -- <!ENTITY % changehistory.data.atts %univ-atts; datatype #IMPLIED outputclass #IMPLIED <!ENTITY % change-historylist.content "(%change-item;)* " <!ENTITY % change-historylist.attributes %changehistory.data.atts; "change-historylist" <!ELEMENT change-historylist %change-historylist.content; <!ATTLIST change-historylist %change-historylist.attributes; <!-- Long Name: Change Item An individual release note. -- <!ENTITY % change-item.content "((%change-person; %change-organization;)*, %change-revisionid;?, %change-request-reference;?, %change-started;?, %change-completed;, %change-summary;?, %data;*) " <!ENTITY % change-item.attributes %changehistory.data.atts; "change-item" <!ELEMENT change-item %change-item.content; <!ATTLIST change-item %change-item.attributes; <!-- Long Name: Change Person: the person who made the change -- <!ENTITY % change-person.content "(#P text)*" <!ENTITY % change-person.attributes

10 Stage 3 proposal: Feature #13102 (Release Management Domain) 10 %changehistory.data.atts; "change-person" <!ELEMENT change-person %change-person.content; <!ATTLIST change-person %change-person.attributes; <!-- Long Name: Change Organization: the organization that instigated (required, suggested) the change -- <!ENTITY % change-organization.content "(#P text)*" <!ENTITY % change-organization.attributes %changehistory.data.atts; "change-organization" <!ELEMENT change-organization %change-organization.content; <!ATTLIST change-organization %change-organization.attributes; <!-- Long Name: Revision ID Specifies the revision ID to which the change applies. Revision IDs are normally specified within publication maps (e.g., Bookmap <revisionid element). -- <!ENTITY % change-revisionid.content "(%data.cnt;)*" <!ENTITY % change-revisionid.attributes %changehistory.data.atts; "change-revisionid" <!ELEMENT change-revisionid %change-revisionid.content; <!ATTLIST change-revisionid %change-revisionid.attributes; <!-- Long Name: Change Request Reference Provides traceablity to an external change request or other ticketing system; -- <!ENTITY % change-request-reference.content "(%change-request-system;?, %change-request-id;?)" <!ENTITY % change-request-reference.attributes %changehistory.data.atts; "change-request-reference" <!ELEMENT change-request-reference %change-request-reference.content; <!ATTLIST change-request-reference %change-request-reference.attributes;

11 Stage 3 proposal: Feature #13102 (Release Management Domain) 11 <!-- Long Name; Change Request System Some description of or identifier for the information system that manages or serves the referenced change request, for example, an issue tracking system. -- <!ENTITY % change-request-system.content "(%data.cnt;)*" <!ENTITY % change-request-system.attributes %changehistory.data.atts; "change-request-system" <!ELEMENT change-request-system %change-request-system.content; <!ATTLIST change-request-system %change-request-system.attributes; <!-- Long Name: Change request ID The identifier of the change request, such as an issue ID or ticket number. -- <!ENTITY % change-request-id.content "(%data.cnt;)*" <!ENTITY % change-request-id.attributes %changehistory.data.atts; "change-request-id" <!ELEMENT change-request-id %change-request-id.content; <!ATTLIST change-request-id %change-request-id.attributes; <!-- Long Name: Change started date -- <!ENTITY % change-started.content "(#P text)*" <!ENTITY % change-started.attributes %changehistory.data.atts; "change-started" <!ELEMENT change-started %change-started.content; <!ATTLIST change-started %change-started.attributes; <!-- Long Name: Change completed date -- <!ENTITY % change-completed.content "(#P text)*" <!ENTITY % change-completed.attributes %changehistory.data.atts;

12 Stage 3 proposal: Feature #13102 (Release Management Domain) 12 "change-completed" <!ELEMENT change-completed %change-completed.content; <!ATTLIST change-completed %change-completed.attributes; <!-- Long Name: Change Summary The portion of the release note that will/may appear in a document -- <!ENTITY % change-summary.content "(%data.cnt;)*" <!ENTITY % change-summary.attributes %changehistory.data.atts; "change-summary" <!ELEMENT change-summary %change-summary.content; <!ATTLIST change-summary %change-summary.attributes; <!-- SPECIALIZATION ATTRIBUTE DECLARATIONS -- <!ATTLIST change-historylist %global-atts; class "- topic/metadata rm-d/change-historylist " <!ATTLIST change-item %global-atts; class "- topic/data rm-d/change-item " <!ATTLIST change-person %global-atts; class "- topic/data rm-d/change-person " <!ATTLIST change-organization %global-atts; class "- topic/data rm-d/change-organization " <!ATTLIST change-revisionid %global-atts; class "- topic/data rm-d/change-revisionid " <!ATTLIST change-request-reference %global-atts; class "- topic/data rm-d/change-request-reference " <!ATTLIST change-started %global-atts; class "- topic/data rm-d/change-started " <!ATTLIST change-completed %global-atts; class "- topic/data rm-d/change-completed " <!ATTLIST change-summary %global-atts; class "- topic/data rm-d/change-summary " <!ATTLIST change-request-system %global-atts; class "- topic/data rm-d/change-request-system " <!ATTLIST change-request-id %global-atts; class "- topic/data rm-d/change-request-id " <!-- ============== End of Release Management domain ======================= --

13 Stage 3 proposal: Feature #13102 (Release Management Domain) 13 Specification documentation The release management domain requires changes to the architectural specification and to the language specification. Changes to the architectural specification The architectural specification requires a new topic describing release management. Release Management Domain The release management domain provides markup that enables content workers to log comments and metadata at the topic level when changes are made. Release notes To help customers locate significant changes in revisions of large documents, the release management domain provides markup to allow the addition of release notes at the topic level, elminating the need for separate release note topics or external files such as spreadsheets or databases. These release notes may be gathered from the topics of a publication by an external process and assembled into an appendix or separate document; no processing support is currently provided. Structure of the release management domain elements This section gives an overview of the release management elements and a brief description of each. This figure shows the structure of the release management elements. Figure 1: Release Management Elements Here is a brief description of each element: change-historylist change-item change-person change-organization change-revisionid change-request-reference change-request-system contains a number of release notes (change-item) applicable to the topic contains a single release note. It contains information about when and by whom the topic was edited during its history. contains the of a person who made the change described by the release note. contains the of a person who made a change described by the release note. contains contains elements that link the change described by the release note to an external system contains the of the external system being referenced

14 Stage 3 proposal: Feature #13102 (Release Management Domain) 14 change-request-id change-started change-completed change-summary contains an ID or other reference number used by the external system contains a string date, with optional time and time zone, that represents the date/time work started on the change described by the release note. contains a string date, with optional time and time zone, that represents the date/time work on the change described by the release note was finished contains a summary description of the change described by the release note Here are example release notes: This figure shows three simple release notes added to a single topic. This topic is used in documentation for two products, A and B. <prolog... <changehistory-list <change-item product="producta productb" <change-persontom Cihak</change-person <change-completed </change-completed <change-summarymade change 1 to both products</changesummary <datadetails of change 1</data </change-item <change-item product="producta" <change-persontom Cihak</change-person <change-completed </change-completed <change-summarymade change 2 to product A</change-summary <datadetails of change 2</data </change-item <change-item product="producta productb" <change-persontom Cihak</change-person <change-completed </change-completed <change-summarymade change 3 to both products</changesummary <datadetails of change 3</data </change-item </changehistory-list... </prolog Figure 2: Excerpt from prolog of topic mytopic Modules The following DITA modules are provided for the release management domain: releasemanagementdomain.mod. releasemanagementdomain.ent releasemanagementdomainmod.xsd, releasemanagementdomaingrp.xsd

15 Stage 3 proposal: Feature #13102 (Release Management Domain) 15 Changes to the language specification The language specification requires new topics for each of the new elements introduced by the release management domain. In addition, the <prolog topic must be modified to show an additional element, <change-historylist. prolog The <prolog element... Changes to prolog element Update <prolog to show new child element, <change-historylist, as follows: Table 1: Changes to <prolog Section Doctypes DITA 1.2 Text Proposed 1.3 Text Modified topic, concept, ditabase, glossary, glossentry, glossgroup, reference, task, machinerytask learningassessment, learningcontent, learningoverview, learningplan, learningsummary ( (author) (any number) then (source) (optional) then (publisher) (optional) then (copyright) (any number) then (critdates) (optional) then (permissions) (optional) then (metadata) (any number) then (resourceid) (any number) then (data or data-about or foreign or unknown) (any number) ) ( (author) (any number) then (source) (optional) then (publisher) (optional) then (copyright) (any number) then (critdates) (optional) then (permissions) (optional) then (metadata or lclom) (any number) then (resourceid) (any number) then (data or data-about or foreign or unknown) (any number) ) ( (author) (any number) then (source) (optional) then (publisher) (optional) then (copyright) (any number) then (critdates) (optional) then (permissions) (optional) then (metadata) (any number) then (resourceid) (any number) then (change-historylist) (optional) then (data or data-about or foreign or unknown) (any number) ) ( (author) (any number) then (source) (optional) then (publisher) (optional) then (copyright) (any number) then (critdates) (optional) then (permissions) (optional) then (metadata or lclom) (any number) then (resourceid) (any number) then (change-historylist) (optional) then (data or data-about or foreign or unknown) (any number) ) change-historylist The <change-historylist element provides a container to hold individual release notes (<change-item). It appears in the topic prolog.. <change-historylist contains these elements: change-item change-person change-organization change-revisionid change-request-reference change-request-system change-request-id change-started change-completed change-summary

16 Stage 3 proposal: Feature #13102 (Release Management Domain) 16 <prolog - topic/metadata rm-d/change-historylist This figure shows three simple release notes added to a single topic. This topic is used in documentation for two products, A and B. <prolog... <changehistory-list <change-item product="producta productb" <change-persontom Cihak</change-person <change-organizationjedec</change-organization <change-completed </change-completed <change-summarymade change 1 to both products</changesummary <datadetails of change 1</data </change-item <change-item product="producta" <change-persontom Cihak</change-person <change-completed </change-completed <change-summarymade change 2 to product A</change-summary <datadetails of change 2</data </change-item <change-item product="producta productb" <change-persontom Cihak</change-person <change-completed </change-completed <change-summarymade change 3 to both products</changesummary <datadetails of change 3</data </change-item </changehistory-list... </prolog Figure 3: Excerpt from prolog of topic mytopic change-item The <change-item element represents a record of a single topic change. <change-item may contain these elements: change-person change-organization change-revisionid change-request-reference change-started change-completed change-summary data

17 Stage 3 proposal: Feature #13102 (Release Management Domain) 17 Note: Each of these elements is optional. <change-historylist - topic/data rm-d/change-item See change-historylist on page 15. change-person The <change-person element holds the of the person making the change. <change-person has text content. <change-item - topic/data rm-d/change-person See change-historylist on page 15. change-organization The <change-organization element holds the of an organization that required the change. <change-organization has text content. <change-item - topic/data rm-d/change-organization See change-historylist on page 15.

18 Stage 3 proposal: Feature #13102 (Release Management Domain) 18 change-revisionid The <change-revisionid element contains a revision id string that can identify the change. <change-revisionid has text content. <change-item - topic/data rm-d/change-revisionid See change-historylist on page 15. change-request-reference The <change-request-reference element contains elements to link the change made to an external tracking system.. <change-request-reference may contain these elements: change-request-system change-request-id <change-item - topic/metadata rm-d/change-request-reference See change-historylist on page 15. change-request-system The <change-request-system element holds the of an external tracking system. <change-request-system has text content. <change-request-reference

19 Stage 3 proposal: Feature #13102 (Release Management Domain) 19 - topic/data rm-d/change-request-system See change-historylist on page 15. change-request-id The <change-request-id element holds the number of a ticket in an external tracking system. <change-request-id has text content. <change-request-reference - topic/data rm-d/change-request-id See change-historylist on page 15. change-started The <change-started element holds date on which the change was initiated. <change-started has text content. It is strongly recommended that the date strings used conform to the ISO 8601 standard (unless a Unix-style machine timestamp is used). The string may contain a date and time or just a date. <change-item - topic/data rm-d/change-started See change-historylist on page 15.

20 Stage 3 proposal: Feature #13102 (Release Management Domain) 20 change-completed The <change-completed element holds date on which the change was completed. <change-completed has text content. It is strongly recommended that the date strings used conform to the ISO 8601 standard (unless a Unix-style machine timestamp is used). The string may contain a date and time or just a date. <change-item - topic/data rm-d/change-completed See change-historylist on page 15. change-summary The <change-summary element a summary description of the change. <change-summary has text content. <change-item - topic/data rm-d/change-summary See change-historylist on page 15.