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.
170 lines
10 KiB
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><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><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><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><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>
|
|
|