diff --git a/README.md b/README.md index 2d1f644..d654ab8 100644 --- a/README.md +++ b/README.md @@ -32,5 +32,54 @@ Document library at [TBD](http://openpowerfoundation.org/docs) The project which control the look and feel of the document is the [Docs-Maven-Plugin project](https://github.com/OpenPOWERFoundation/Docs-Maven-Plugin). +## Contributions To contribute to the OpenPOWER Foundation template document project, contact Jeff Scheel \([scheel@us.ibm.com](mailto://scheel@us.ibm.com)\) or Jeff Brown \([jeffdb@us.ibm.com](mailto://jeffdb@us.ibm.com)\). + +Contributions to this project should conform to the `Developer Certificate +of Origin` as defined at http://elinux.org/Developer_Certificate_Of_Origin. +Commits to this project need to contain the following line to indicate +the submitter accepts the DCO: +``` +Signed-off-by: Your Name +``` +By contributing in this way, you agree to the terms as follows: +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + diff --git a/template/bk_main.xml b/template/bk_main.xml index b021601..1ae4187 100644 --- a/template/bk_main.xml +++ b/template/bk_main.xml @@ -33,7 +33,7 @@ OpenPOWER Foundation - Revision 0.9.2 + Revision 0.9.3 OpenPOWER @@ -48,16 +48,31 @@ Copyright details are filled in by the template. - - - Abstract text + 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. + 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 + OpenPOWER Foundation Work Group (WG) Process document. - --> + + 2016-02-25 + + + + Version 0.9.3: Technical and process updates. Addition of documentation lifecycle and git command cheat sheets. + + + + 2016-02-25 diff --git a/template/ch_example.xml b/template/ch_example.xml index 8afa822..352c126 100644 --- a/template/ch_example.xml +++ b/template/ch_example.xml @@ -61,10 +61,12 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_examples"> Example figure - + + Raw images such as the bitmap (bmp) file above may become blurry as they are scaled. + Scalable graphic formats like SVG (Scalable Vector Graphics) embed and scale the best.
diff --git a/template/ch_template_overview.xml b/template/ch_template_overview.xml index a12b212..2b42e11 100644 --- a/template/ch_template_overview.xml +++ b/template/ch_template_overview.xml @@ -10,37 +10,54 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> The major sections of this document addresses the following topics: - Get started: This section details tools and commands used to contribute to OpenPOWER documentation. - All users who are new to OpenPOWER Foundation documentation should start here. + : + This section details tools and commands used to contribute to OpenPOWER documentation. + All users who are new to OpenPOWER Foundation documentation should start here. - Creating a new document: This section provides step-by-step instructions on how to create a new document - from scratch. Use this section to start a new document. + : + This section provides step-by-step instructions on how to create a new document + from scratch. Use this section to start a new document. - Modifying an existing document: This section highlights common steps in editing an existing OpenPOWER - Foundation document. Use this section as a guideline for contributing to an existing document. + : + This section highlights common steps in editing an existing OpenPOWER + Foundation document. Use this section as a guideline for contributing to an existing document. - Debugging build failures: This section provides examples of the two most common types of build failures - and helps users find the relevant failure information. + : + This section provides examples of the two most common types of build failures + and helps users find the relevant failure information. - Understanding the project structure: This section provides detailed descriptions of the various project + : + This section explains key document types and the appropriate work flow for publishing OpenPOWER Foundation + documents. + + + : + This section provides detailed descriptions of the various project components and their roles in the documentation creation process. - Policies and conventions: This secion contains - the generally accepted guidelines for creating OpenPOWER documentation. Use this section as a reference - for documentation style beyond template provided features. + : This section contains + the generally accepted guidelines for creating OpenPOWER documentation. Use this section as a reference + for documentation style beyond template provided features. + + + : + This section answers common questions. Use this section when the other sections + do not answer your questions. - Frequently asked questions: This section answers common questions. Use this section when the other sections - do not answer your questions. + : + This section contains examples of commonly used git commands. Reference this section + to find information on a specific git operation. - Where to find more information: This section provides pointers to on-line information about XML, Docbook, - Maven, and other relevant references. + : + This section provides pointers to on-line information about XML, Docbook, + Maven, and other relevant references. @@ -51,9 +68,11 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> + + diff --git a/template/figures/project_process_non-std_track_graphic.odg b/template/figures/project_process_non-std_track_graphic.odg new file mode 100644 index 0000000..9e4852d Binary files /dev/null and b/template/figures/project_process_non-std_track_graphic.odg differ diff --git a/template/figures/project_process_non-std_track_graphic.svg b/template/figures/project_process_non-std_track_graphic.svg new file mode 100644 index 0000000..0ebe6cc --- /dev/null +++ b/template/figures/project_process_non-std_track_graphic.svg @@ -0,0 +1,151 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Public, Member Confidential,Work Group Confidential + + + + + Public, Member Confidential,Work Group Confidential + + + + + Work Group NoteDraft + + + + + Work Group NoteReview Draft + + + + + Work Group Note + + + + + + + \ No newline at end of file diff --git a/template/figures/project_process_std_track_graphic.odg b/template/figures/project_process_std_track_graphic.odg new file mode 100644 index 0000000..21c8e57 Binary files /dev/null and b/template/figures/project_process_std_track_graphic.odg differ diff --git a/template/figures/project_process_std_track_graphic.svg b/template/figures/project_process_std_track_graphic.svg new file mode 100644 index 0000000..3da0756 --- /dev/null +++ b/template/figures/project_process_std_track_graphic.svg @@ -0,0 +1,208 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Public, Member Confidential,Work Group Confidential + + + + + Public, Member Confidential,Work Group Confidential + + + + + + + + + + + Public + + + + + + + + + + + + + + + + + Public + + + + + + + + + + + Public, Member Confidential,Work Group Confidential + + + + + Work GroupSpecificationDraft + + + + + Work GroupSpecification ReviewDraft + + + + + Work GroupSpecification + + + + + CandidateOpenPOWERStandard + + + + + OpenPOWERStandard + + + + + + + \ No newline at end of file diff --git a/template/figures/project_structure_graphic.bmp b/template/figures/project_structure_graphic.bmp deleted file mode 100644 index 3b7f4af..0000000 Binary files a/template/figures/project_structure_graphic.bmp and /dev/null differ diff --git a/template/figures/project_structure_graphic.odg b/template/figures/project_structure_graphic.odg index 17e60d4..807414e 100644 Binary files a/template/figures/project_structure_graphic.odg and b/template/figures/project_structure_graphic.odg differ diff --git a/template/figures/project_structure_graphic.svg b/template/figures/project_structure_graphic.svg new file mode 100644 index 0000000..9818b05 --- /dev/null +++ b/template/figures/project_structure_graphic.svg @@ -0,0 +1,451 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + + + + Docs-Master + + + + + Docs-Template + + + + + common + + + + + pom.xml + + + + + ch_preface.xml + + + + + ... + + + + + app_foundation.xml + + + + + ... + + + + + template + + + + + pom.xml + + + + + bk_main.xml + + + + + ... + + + + + pom.xml + + + + + ... + + + + + my_project + + + + + my_doc_1 + + + + + pom.xml + + + + + bk_main.xml + + + + + ... + + + + + pom.xml + + + + + ... + + + + + my_doc_2 + + + + + bk_main.xml + + + + + pom.xml + + + + + ... + + + + + + + + + + + + + + + + + + + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + “Master document framework” + + + + + “Common files” + + + + + “Master POM” + + + + + “Master Template Guide” + + + + + “Main book file” + + + + + “Document POM” + + + + + “Workgroup POM” + + + + + “A project” + + + + + “A document” + + + + + “Another document” + + + + + “Workgroup POM” + + + + + + + \ No newline at end of file diff --git a/template/pom.xml b/template/pom.xml index 1da48cf..b32d788 100644 --- a/template/pom.xml +++ b/template/pom.xml @@ -76,7 +76,7 @@ template-guide review - + diff --git a/template/sec_template_debugging.xml b/template/sec_template_debugging.xml index ef17853..d8fa277 100644 --- a/template/sec_template_debugging.xml +++ b/template/sec_template_debugging.xml @@ -1,7 +1,7 @@
- Debugging build failures + Debugging build failures Maven/docbkx failures generally fall into these categories: Project structure errors diff --git a/template/sec_template_existing_document.xml b/template/sec_template_existing_document.xml index ab3fe52..7e561c1 100644 --- a/template/sec_template_existing_document.xml +++ b/template/sec_template_existing_document.xml @@ -1,7 +1,7 @@
- Modifying an existing document + Modifying an existing document To begin editing an existing document, you must first clone two projects -- the master document framework project and the specific document project. Begin by cloning the master document as described in . @@ -70,5 +70,10 @@ Checking connectivity... done. the base project directory will build all projects identified in the <module> list in the top-level pom.xml file, known as the "workgroup-pom". + You are now ready to begin making updates. Before diving deeply into new text, + you may want to review + to ensure that proper Work Product, + Work Process, and security values are selected for your document. +
diff --git a/template/sec_template_faq.xml b/template/sec_template_faq.xml index 30b4640..06b1800 100644 --- a/template/sec_template_faq.xml +++ b/template/sec_template_faq.xml @@ -1,7 +1,7 @@
- Frequently asked questions + Frequently asked questions The list of questions and answers may be helpful to first time document writers: diff --git a/template/sec_template_getting_started.xml b/template/sec_template_getting_started.xml index 9302a65..c4f828c 100644 --- a/template/sec_template_getting_started.xml +++ b/template/sec_template_getting_started.xml @@ -1,7 +1,7 @@
- Getting started + Getting started To begin contributing to the OpenPOWER Foundation documentation, the following steps must be completed: diff --git a/template/sec_template_git_commands.xml b/template/sec_template_git_commands.xml new file mode 100644 index 0000000..d971d20 --- /dev/null +++ b/template/sec_template_git_commands.xml @@ -0,0 +1,166 @@ +
+ + Common git commands + This section provides a list of commonly used git commands invocations. All commands shown, except + the first one (git clone must be issued from within the project directory. + + + + + To clone a git tree for first time or temporary use via http, + use:$ git clone <URL> + The <URL> value for OpenPOWER Foundation GitHub projects can be found on the project web pages. + They generally take the form of https://github.com/OpenPOWERFoundation/project_name where the + project_name can be found on the OpenPOWER Foundation Git Hub community page at + https://github.com/OpenPOWERFoundation. The result of this + command will be a new directory with the same name as the project and in which will be the project files. + Trees can only be cloned once. To update a tree, use a git pull or git merge + command. + When cloning from a private tree, you will be prompted for your GitHub userid and password. + + + + To update a git tree with new files from the remote repository, + use:$ git pull + This command assumes that the local tree has not been updated since the clone or last pull. If updates have been made to + the local tree, the command will fail. Use the git status command to see what has changed in a local tree. + When pulling from a private tree, you will be prompted for your GitHub userid and password. + + + + To see the status of the local repository, + use:$ git status + This command identifies files which have changed in the local repository and provides suggestions on how to handle. + + Adding the -s parameter to the end of the command will provide a simplified view in which changed files + are listed with flags such as M for modified files, A for newly added files, + and ?? for new or unknown files. This parameter also suppresses suggested action information for the files. + + + + To add a new file or directory to a git tree, + use:$ git add <new_file> + The <new_file> value can be either a file or a whole directory and may include the path to + the target file or directory. This command will convert the status of file in the git status -s + command from ?? to A or move it from the "Untracked files" section to the + "Changes to be committed" section of the git status command. + + + + To remove a file from a git tree, + use:$ git rm <file> + The <file> value must be a file and may include wildcard characters or the path to + the target file. This command will both remove the file(s) from the directory and the git tree. Removed files will show in + a status modifier of D in the git status -s + command and be reflected in the "Changes not staged for commit" section of thegit status command + with a "deleted:" status. + + + + To remove a directory from a git tree, + use:$ git rm -rf <directory> + The <directory> value must be a directory name and may include wildcard characters or the path to + the target directory. This command will remove all files in the directory from the git tree, but will not remove the directory locally. + Standard operating system commands such as the Linux rmdir <directory> command must be issued separately to + remove the local directory. All removed files will show in + a status modifier of D in the git status -s + command and be reflected in the "Changes not staged for commit" section of thegit status command with a + "deleted:" status. Because git does not + track directories, they will not be reflected in status. + + + + To move or rename a file or directory in a git tree, + use:$ git mv <source> <destination> + The <source> value must be a file or directory and may include the path to + the target file. The <destination> value may be a file (if renaming a file) or a directory + if moving a file or directory. + This command will move or rename the file(s) in both the local and remote the git trees. + + + + To commit all local changes to the staging area for a git tree, + use:$ git commit -a + This command will invoke an editor for a commit message. A well-formatted commit message includes a + title on the first line, a blank line, one or more lines of details describing the changes, and a Developer's + Certificate of Orig (DCO) Sign-off statement at the end. Signed-off-by: Your name <your_email@domain.com> + For information on the DCO, see Developer Certificate Of Origin at + http://elinux.org/Developer_Certificate_Of_Origin. + + + + To push all locally staged changes to the remote git tree, + use:$ git push + When pushing to a private tree, you will be prompted for your GitHub userid and password. + + + + To see what tags exist in a git tree, + use:$ git tag + + + + To create a new tag locally, + use:$ git tag -a <tag_name> -m"text" + The tag_name represents the simple value of the tag. The text string + provides more description of the tag for readibility. + This command simply tags locally. See the next command for how to push the tag to the remote repository. + + + + To push a new tag from the local tree to the remote tree, + use:$ git push origin <tag_name> + This commands assumes the git tag command has been run on the local tree. + + + + To discard changes from a locally changed file and return to the last copy, + use:$ git checkout -- <file> + The <file> value must be a file and may include wildcard characters or the path to + the target file. + + + + To identify what changes have been made locally to a file + use:$ git diff <file> + The <file> value must be a file and may include wildcard characters or the path to + the target file. The output will be in format similar to the standalone diff command. + + + + + Additional resources about git can be found online at the following locations: + + + + + The GitHub Glossary at + https://help.github.com/articles/github-glossary/. + This site provides a list of common terms associated with git and GitHub. + + + + The GitHub Git Cheat Sheet at + + https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf. + This two page pdf provides a quick summary of many common commands. + + + + + The Git Reference at + http://gitref.org/. This is a deeper and more comprehensive reference of important commands. + + + + The git-scm.com Documentation library at + http://git-scm.com/doc. This site provides education in the form of books, videos, + and other tutorials for common git activities. + + + + + +
+ diff --git a/template/sec_template_new_document.xml b/template/sec_template_new_document.xml index 845f31b..6cefc66 100644 --- a/template/sec_template_new_document.xml +++ b/template/sec_template_new_document.xml @@ -1,7 +1,7 @@
- Creating a new document + Creating a new document Creating a new document from scratch follows four simple steps: @@ -169,9 +169,16 @@ Checking connectivity... done. and bk_main.xml. Within these two files are XML comment tags that begin "<!-- TODO:" to identify places which need customization. The surrounding comments will provide guidance on what needs to change and how it may be changed. Simply work through each item, making updates as requested. + Pick your setting for document work product type (<workProduct>, + work flow status (<documentStatus>), and + security (<security>) + carefully. provides an overview of the process + and details the various settings needed in the document core project files. If you still have + questions after reading this section, consult with your Technical Steering Committee + representative. Be sure to remember two key values you used in the pom.xml file, <webhelpDirname> and <pdfFilenameBase>, as these will be used to locate your generated document. - When complete, be sure to build your new document using standard maven commands like + When ready, build your new document using standard maven commands like this:$ cd my_proj/my_doc $ mvn clean [INFO] Scanning for projects... diff --git a/template/sec_template_policies.xml b/template/sec_template_policies.xml index 80b82ef..93d6262 100644 --- a/template/sec_template_policies.xml +++ b/template/sec_template_policies.xml @@ -1,7 +1,7 @@
- Policies and conventions + Policies and conventions Most document style policies are established simply by using the template documentation framework. However, by applying some conventions to the document source structure, community members will be able to work across more d ocumentation projects. @@ -28,14 +28,14 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_policies"> - In addition to documentation documentation structure, general community/project guidelines are as follows + In addition to documentation structure, general community/project guidelines are as follows: Contributions to the documentation projects should conform to the Developer Certificate Of Origin as defined at - http://elinux.org/Developer_Certificate_Of_Origin. Submissions of patches to GitHub project need + http://elinux.org/Developer_Certificate_Of_Origin. Commits to the GitHub project need to contain the following line to indicate the submitter accepts the - DCO:Signed-off-by: Your name >your_email@domain.com + DCO:Signed-off-by: Your name <your_email@domain.com> diff --git a/template/sec_template_process.xml b/template/sec_template_process.xml new file mode 100644 index 0000000..68e5726 --- /dev/null +++ b/template/sec_template_process.xml @@ -0,0 +1,153 @@ +
+ + Publishing OpenPOWER Documents + The OpenPOWER Foundation Work Group (WG) Process 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. + + 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." + + 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: + +
+ Document work flow for Standard Track Work Products + + + + + +
+ + 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. + + Non-standard Track Work Products exist simply as Work Group Notes. Their document + lifecycle follows this simplified workflow: + +
+ Document work flow for Non-standard Track Work Products + + + + + +
+ + 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). + + Once these decisions have been made, then they can be reflected into the document in the following ways: + + + + + The document Work Product type is defined in the document pom.xml file with the + <workProduct> variable. Valid settings are workgroupNotes, + workgroupSpecification, candidateStandard, and openpowerStandard. + Select the appropriate setting in the following section: + +workgroupNotes + + +]]> + + + + The document security is set in the document pom.xml file with the + <security> variable. Valid settings are public, + foundationConfidential, and workgroupConfidential. + Select the appropriate setting in the following section: + +workgroupConfidential + +]]> + + + + The document work flow status is set in the document pom.xml file with the + <documentStatus> variable. Valid settings are draft, + review, and published. + Select the appropriate setting in the following section: + +draft + +]]> + + + + The final place to make updates to a new document is in the <abstract> section of + the bk_main.xml file for the document. This section needs to be updated with the appropriate + work group information and document information. Typical text appears as follows: + + + 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. + 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 OpenPOWER Foundation Work Group (WG) + Process document. +]]> + 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. + + + + +
+ diff --git a/template/sec_template_references.xml b/template/sec_template_references.xml index 472afc6..fa18a1f 100644 --- a/template/sec_template_references.xml +++ b/template/sec_template_references.xml @@ -1,7 +1,7 @@
- Where to find more information + Finding more information The following lists of references may be helpful in learning about XML, Docbook, and/or Maven: diff --git a/template/sec_template_structure.xml b/template/sec_template_structure.xml index 0a8ed64..50fad8a 100644 --- a/template/sec_template_structure.xml +++ b/template/sec_template_structure.xml @@ -1,7 +1,7 @@
- Understanding the project structure + Understanding the project structure The OpenPOWER Foundation documentation build process involves dependency on a common framework and shared files. As such a deeper explanation about the relationships of key projects and their components may be helpful to prevent and diagnose documentation build problems. This section @@ -23,7 +23,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure"> Directory structure and key files in the OpenPOWER Foundation Docbook projects - +