You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
CAPI-SNAP-Doc/template/sec_template_process.xml

170 lines
10 KiB
XML

<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process">
<title xml:id="section_template_process_title">Publishing OpenPOWER Documents</title>
<para>The <citetitle>OpenPOWER Foundation Work Group (WG) Process</citetitle> document
found in the OpenPOWER Foundation Members Community documents is the definitive guide for understanding
OpenPOWER Foundation documents and their work flow. The section strives to
provide an overview to help writers understand enough of the basics to know how to prepare their
document and what to expect as they proceed through various stages of document development from first
draft to specification publish.</para>
<para>The first key concept to understand about OpenPOWER Foundation documents and the first
decision to make when creating a new document is available document types or "Work Products".
These fall into one of two categories -- Standards Track or Non-standards Track -- with the simple
distinguishing factor being use. If the purpose of a document is to define a specification or standard
for hardware or software, then the document is "Standards Track". Everything else is "Non-standards
Track." For example, this document is a non-stardard work product.</para>
<para>Standards Track Work Products begin their life as Work Group Specification and may ultimately
become an OpenPOWER Standard. Their document lifecycle is defined in the following illustration:</para>
<figure pgwide="1" xml:id="project_process_std_track_label">
<title>Document work flow for Standard Track Work Products</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/project_process_std_track_graphic.svg" format="SVG" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<para>Standard Track Work Products begin their lives as Work Group Specifications and have security classifications
of Public (non-confidental),
Members-only (OpenPOWER Foundation Confidental), or Work Group-only (OpenPOWER Work Group Confidential).
The security classification impacts the review type -- either public or internal to the Foundation -- as appropriate.
Only Work Group Specifications classified as Public may proceed into OpenPOWER Standard Documents. Confidential
documents will remain Work Group Specifications.</para>
<para>Non-standard Track Work Products exist simply as Work Group Notes. Their document
lifecycle follows this simplified workflow:</para>
<figure pgwide="1" xml:id="project_process_non-std_track_label">
<title>Document work flow for Non-standard Track Work Products</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/project_process_non-std_track_graphic.svg" format="SVG" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<para>Non-standard Track, Work Group Notes begin as Drafts and drop the "Draft" annotation once reviewed. Like
Standard Track Work Products, they may have security classifications as Public (non-confidential), Members-only
(OpenPOWER Foundation Confidential), or Work-Group only (OpenPOWER Work Group Confidential) which will
in turn dictate the review context (public or private).</para>
<para>Once these decisions have been made, then they can be reflected into the document in the following ways:</para>
<orderedlist>
<listitem>
<para>The document Work Product type is defined in the document <literal>pom.xml</literal> file with the
<literal>&lt;workProduct></literal> variable. Valid settings are <literal>workgroupNotes</literal>,
<literal>workgroupSpecification</literal>, <literal>candidateStandard</literal>, and <literal>openpowerStandard</literal>.
Select the appropriate setting in the following section:
<programlisting><![CDATA[<!-- TODO: Define the appropriate work product type. These values are defined by the
IPR Policy. Consult with the Work Group Chair or a Technical Steering
Committee member if you have questions about which value to select.
If no value is provided below, the document will default to "Work Group
Notes".-->
<workProduct>workgroupNotes</workProduct>
<!-- workProduct>workgroupSpecification</workProduct -->
<!-- workProduct>candidateStandard</workProduct -->
<!-- workProduct>openpowerStandard</workProduct -->]]></programlisting></para>
</listitem>
<listitem>
<para>The document security is set in the document <literal>pom.xml</literal> file with the
<literal>&lt;security></literal> variable. Valid settings are <literal>public</literal>,
<literal>foundationConfidential</literal>, and <literal>workgroupConfidential</literal>.
Select the appropriate setting in the following section:
<programlisting><![CDATA[<!-- TODO: Set the appropriate security policy for the document. For documents
which are not "public" this will affect the document title page and
create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:
public = this document may be shared outside the
foundation and thus this setting must be
used only when completely sure it allowed
foundationConfidential = this document may be shared freely with
OpenPOWER Foundation members but may not be
shared publicly
workgroupConfidential = this document may only be shared within the
work group and should not be shared with
other Foundation members or the public
The appropriate starting security for a new document is "workgroupConfidential". -->
<security>workgroupConfidential</security>
<!-- security>foundationConfidential</security -->
<!-- security>public</security -->]]></programlisting></para>
</listitem>
<listitem>
<para>The document work flow status is set in the document <literal>pom.xml</literal> file with the
<literal>&lt;documentStatus></literal> variable. Valid settings are <literal>draft</literal>,
<literal>review</literal>, and <literal>published</literal>.
Select the appropriate setting in the following section:
<programlisting><![CDATA[<!-- TODO: Set the appropriate work flow status for the document. For documents
which are not "published" this will affect the document title page
and create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:
published = this document has completed all reviews and has
been published
draft = this document is actively being updated and has
not yet been reviewed
review = this document is presently being reviewed
The appropriate starting security for a new document is "draft". -->
<documentStatus>draft</documentStatus>
<!-- documentStatus>review</documentStatus -->
<!-- documentStatus>publish</documentStatus -->]]></programlisting></para>
</listitem>
<listitem>
<para>The final place to make updates to a new document is in the <literal>&lt;abstract></literal> section of
the <literal>bk_main.xml</literal> file for the document. This section needs to be updated with the appropriate
work group information and document information. Typical text appears as follows:
<programlisting><![CDATA[<!-- TODO: Update the following text with the correct document description (first
paragraph), Work Group name, and Work Product track (both in second
paragraph). -->
<abstract>
<para>The purpose of the Master Template Guide document is to provide a guide
for OpenPOWER documentation writers. As such, it provides directions, policies,
references, and examples of the XML Docbook environment. It is intended to be
used both in final product form (PDF and html) as a document and in source form
as a template for new documents.</para>
<para>This document is a Non-standard Track, Work Group Note work product
owned by the System Software Workgroup and handled in compliance with the
requirements outlined in the <citetitle>OpenPOWER Foundation Work Group (WG)
Process</citetitle> document.</para>
</abstract>]]></programlisting></para>
<para>As stated in the comment text of the book file, the first paragraph provides a typical abstract
statement about your particular document. The second paragraph provides more structured
text which should be updated with the appropriate Work Group name, Work Product type,
and Work Product process. The rest of the information in this paragraph should remain as-is.</para>
</listitem>
</orderedlist>
</section>