Initial start of converting the Word outline to Rest

Thanks to Scott Zemerick <scott.zemerick@tmctechnologies.com> for
the analysis and ideas that led to this.

14 files changed, 274 insertions, 0 deletions

diff --git a/software-engineering-handbook/README b/software-engineering-handbook/README
new file mode 100644
index 0000000..5897350
--- /dev/null
+++ b/software-engineering-handbook/README
@@ -0,0 +1,7 @@
+This is a work in process. The initial parts of
+RTEMS-Engineering-Standards-v3.docx have been converted to Rest. The
+remaining sections need to be converted. And as marked, there are
+sections where content from the Wiki needs to be converted to Rest
+and included directly here.
+
+--joel
diff --git a/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx b/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx
new file mode 100755
index 0000000..7fbfb9e
--- /dev/null
+++ b/software-engineering-handbook/RTEMS-Engineering-Standards-v3.docx
diff --git a/software-engineering-handbook/change-management.rst b/software-engineering-handbook/change-management.rst
new file mode 100644
index 0000000..ff04675
--- /dev/null
+++ b/software-engineering-handbook/change-management.rst
@@ -0,0 +1,14 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+Change Manaegment
+*****************
+
+Major decisions about RTEMS are made by the core developers in concert
+with the user community, guided by the Mission Statement. We provide
+access to our development sources via a Git Repository (see these
+Instructions for details).
+
+TBD - ???
diff --git a/software-engineering-handbook/coding-standards.rst b/software-engineering-handbook/coding-standards.rst
new file mode 100644
index 0000000..0af9c78
--- /dev/null
+++ b/software-engineering-handbook/coding-standards.rst
@@ -0,0 +1,11 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+Coding Standards
+****************
+
+TBD  - Convert the following to Rest and insert into this file
+TBD  - https://devel.rtems.org/wiki/Developer/Coding/Conventions
+TBD  - https://devel.rtems.org/wiki/Developer/Coding
diff --git a/software-engineering-handbook/conf.py b/software-engineering-handbook/conf.py
new file mode 100644
index 0000000..a4da3ff
--- /dev/null
+++ b/software-engineering-handbook/conf.py
@@ -0,0 +1,14 @@
+import sys, os
+sys.path.append(os.path.abspath('../common/'))
+
+from conf import *
+
+project = "RTEMS Software Engineering Handbook"
+
+latex_documents = [
+    ('index',
+     'software-engineering-handbook.tex',
+     u'RTEMS Software Engineering Handbook',
+     u'RTEMS Documentation Project',
+     'manual'),
+]
diff --git a/software-engineering-handbook/index.rst b/software-engineering-handbook/index.rst
new file mode 100644
index 0000000..224e46a
--- /dev/null
+++ b/software-engineering-handbook/index.rst
@@ -0,0 +1,56 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: COPYRIGHT (c) 2016-2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+================================================
+RTEMS Software Engineering Handbook (|version|).
+================================================
+
+ | **COPYRIGHT (c) 1988 - 2015.**
+ | **On-Line Applications Research Corporation (OAR).**
+ | **COPYRIGHT (c) 2016-2018.**
+ | **RTEMS Foundation, The RTEMS Documentation Project**
+
+ | **License:**
+ |  Creative Commons Attribution-ShareAlike 4.0 International Public License
+ |  https://creativecommons.org/licenses/by-sa/4.0/legalcode
+
+The authors have used their best efforts in preparing this material.  These
+efforts include the development, research, and testing of the theories and
+programs to determine their effectiveness.  No warranty of any kind, expressed
+or implied, with regard to the software or the material contained in this
+document is provided.  No liability arising out of the application or use of
+any product described in this document is assumed.  The authors reserve the
+right to revise this material and to make changes from time to time in the
+content hereof without obligation to notify anyone of such revision or changes.
+
+The RTEMS Project is hosted at http://www.rtems.org/.  Any inquiries concerning
+RTEMS, its related support components, or its documentation should be directed
+to the Community Project hosted at http://www.rtems.org/.
+
+.. topic:: RTEMS Online Resources
+
+  ================  =============================
+  Home              https://www.rtems.org/
+  Developers        https://devel.rtems.org/
+  Documentation     https://docs.rtems.org/
+  Bug Reporting     https://devel.rtems.org/query
+  Mailing Lists     https://lists.rtems.org/
+  Git Repositories  https://git.rtems.org/
+  ================  =============================
+
+.. toctree::
+	:maxdepth: 4
+	:numbered:
+
+	preface
+        prequalification
+        stakeholders
+        software-development-management
+	function_and_variable
+	concept
+
+* :ref:`genindex`
diff --git a/software-engineering-handbook/issue-tracking.rst b/software-engineering-handbook/issue-tracking.rst
new file mode 100644
index 0000000..47ec03a
--- /dev/null
+++ b/software-engineering-handbook/issue-tracking.rst
@@ -0,0 +1,18 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+Issue Tracking
+**************
+
+This section discussions Trac usage and tickets.
+
+Related URLs to review for conversion to this document
+
+https://devel.rtems.org/wiki/NewTicket
+https://devel.rtems.org/wiki/Developer/Bug_Reporting
+
+Querying existing tickets (keep as a link)
+
+https://devel.rtems.org/query
diff --git a/software-engineering-handbook/preface.rst b/software-engineering-handbook/preface.rst
new file mode 100644
index 0000000..81b16df
--- /dev/null
+++ b/software-engineering-handbook/preface.rst
@@ -0,0 +1,26 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+Preface
+*******
+
+The Real Time Executive for Multiprocessor Systems (RTEMS) operating
+systems is a layered system with each of the public APIs implemented in
+terms of a common foundation layer called the SuperCore. RTEMS provides
+full capabilities for management of tasks, interrupts time, and multiple
+processors in addition to those features typical of generic operating
+systems. RTEMS has been implemented in both the Ada and C programming
+languages.
+
+.. topic: RTEMS Mission Statement
+
+  RTEMS development aims to provide a free deterministic real-time operating
+  system targeted towards deeply embedded systems which is competitive
+  with closed source products. The RTEMS project encourages the support
+  and use of standard APIs in order to promote application portability
+  and ease porting other packages to the RTEMS environment. Source:
+  https://devel.rtems.org/wiki/Mission_Statement
+
+The RTEMS development effort uses an open development environment in which all users collaborate to improve RTEMS. The RTEMS cross development toolset is based upon the free GNU tools and the open source C Library newlib. RTEMS supports many host platforms and target architectures.
diff --git a/software-engineering-handbook/prequalification.rst b/software-engineering-handbook/prequalification.rst
new file mode 100644
index 0000000..5234dbf
--- /dev/null
+++ b/software-engineering-handbook/prequalification.rst
@@ -0,0 +1,68 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: COPYRIGHT (c) 2016-2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+Introduction to Pre-Qualification
+*********************************
+
+RTEMS has a long history of being used to support critical
+applications. In some of these application domains, there are standards
+(e.g., DO-178C, NPR 7150.2) which define the expectations for the
+processes used to develop software and the associated artifacts. These
+standards typically do not specify software functionality but address
+topics like requirements definition, traceability, having a documented
+change process, coding style, testing requirements, and a user’s
+manual. During system test, these standards call for a review – usually
+by an independent entity – that the standard has been adhered too. These
+reviews cover a broad variety of topics and activities, but the process
+is generally referred to as qualification, verification, or auditing
+against the specific standard in use. The RTEMS Project will use the
+term “qualification” independent of the standard.
+
+The goal of the RTEMS Qualification Project is to make RTEMS easier
+to review regardless of the standard chosen. Quite specifically,
+the RTEMS Qualification effort will NOT produce a directly qualified
+product or artifacts in the format dictated by a specific organization
+or standard. The goal is to make RTEMS itself, documentation, testing
+infrastructure, etc. more closely align with the information requirements
+of these high integrity qualification standards. In addition to improving
+the items that a mature, high quality open source project will have,
+there are additional artifacts needed for a qualification effort that
+no known open source project possesses. Specifically, requirements and
+the associated traceability to source code, tests, and documentation
+are needed.
+
+The RTEMS Qualification Project is technically
+“pre-qualification”. True qualification must be performed on the
+project’s target hardware in a system context. The FAA has provided
+guidance for Reusable Software Components (FAA-AC20-148) and this
+effort should follow that guidance. The open RTEMS Project, with the
+assistance of domain experts, will possess and maintain the master
+technical information needed in a qualification effort. Consultants
+will provide the services required to tailor the master information,
+perform testing on specific system hardware, and to guide end users in
+using the master technical data in the context of a particular standard.
+
+The RTEMS Qualification Project will broadly address two areas. The first area is suggesting areas of improvement for automated project infrastructure and the master technical data that has traditionally been provided by the RTEMS Project. For example, the RTEMS Qualification could suggest specific improvements to code coverage reports. The teams focused on qualification should be able to provide resources for improving the automated project infrastructure and master technical data for RTEMS. The term “resources” is often used by open source projects to refer to volunteer code contributions or funding. Although code contributions in this area are important and always welcome, funding is also important. At a minimum, ongoing funding is needed for maintenance and upgrades of the RTEMS Project server infrastructure, addition of services to those servers, and core contributors to review submissions
+
+The second area is the creation and maintenance of master technical
+data that has traditionally not been owned or maintained by the RTEMS
+Project. The most obvious example of this is a requirements set with
+proper infrastructure for tracing requirements through code to test
+and documentation. It is expected that these will be maintained by the
+RTEMS Qualification Project. They will be evaluated for adoption by
+the main RTEMS Project but the additional maintenance burden imposed
+will be a strong factor in this consideration. It behooves the RTEMS
+Qualification Project to limit dependence on manual checks and ensure
+that automation and ongoing support for that automation is contributed
+to the RTEMS Project.
+
+It is expected that the RTEMS Qualification Project will create and
+maintain maps from the RTEMS master technical data to the various
+qualification standards. It will maintain “scorecards” which
+identify how the RTEMS Project is currently doing when reviewed per each
+standard. These will be maintained in the open as community resources
+which will guide the community in improving its infrastructure.
diff --git a/software-engineering-handbook/software-development-git-users.rst b/software-engineering-handbook/software-development-git-users.rst
new file mode 100644
index 0000000..ebd79bb
--- /dev/null
+++ b/software-engineering-handbook/software-development-git-users.rst
@@ -0,0 +1,11 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+
+Software Development (Git Users)
+********************************
+
+TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Users to Rest
+TBD - and insert here.
diff --git a/software-engineering-handbook/software-development-management.rst b/software-engineering-handbook/software-development-management.rst
new file mode 100644
index 0000000..f10349a
--- /dev/null
+++ b/software-engineering-handbook/software-development-management.rst
@@ -0,0 +1,22 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+
+Software Development Management
+*******************************
+
+TBD - Convert https://devel.rtems.org/wiki/TBR/Website/WhyContribute to Rest
+TBD - and insert here
+
+
+
+
+.. COMMENT: Subsections
+.. toctree::
+
+    software-development-git-users
+    coding-standards
+    change-management
+    issue-tracking
diff --git a/software-engineering-handbook/stakeholders.rst b/software-engineering-handbook/stakeholders.rst
new file mode 100644
index 0000000..5046269
--- /dev/null
+++ b/software-engineering-handbook/stakeholders.rst
@@ -0,0 +1,15 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2018.
+.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
+
+Qualification - Stakeholder Involvement
+***************************************
+
+Qualification of RTEMS is a specialized activity and only specific users
+of RTEMS will complete a formal qualification activity. The RTEMS Project
+cannot self-fund this entire activity and requires stakeholder to invest
+in an ongoing basis to ensure the any investment they make is maintained
+and viable in an ongoing basis. The RTEMS core developers view steady
+support of the qualification effort as necessary to continue to lower
+the overall costs of qualification RTEMS.
diff --git a/software-engineering-handbook/wscript b/software-engineering-handbook/wscript
new file mode 100644
index 0000000..26ab0ca
--- /dev/null
+++ b/software-engineering-handbook/wscript
@@ -0,0 +1,11 @@
+from sys import path
+from os.path import abspath
+path.append(abspath('../common/'))
+
+from waf import cmd_configure as configure
+from waf import cmd_build as build
+from waf import cmd_options as options
+from waf import spell
+from waf import cmd_spell
+from waf import linkcheck
+from waf import cmd_linkcheck
diff --git a/wscript b/wscript
index 5ce7f0d..41a1e9e 100644
--- a/wscript
+++ b/wscript
@@ -17,6 +17,7 @@ build_all = ['user',
              'bsp-howto',
              'posix-users',
              'posix-compliance',
+             'software-engineering-handbook',
              'filesystem',
              'networking',
              'shell',