Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add software plan blocks #30

Merged
merged 3 commits into from May 22, 2019
Merged

Add software plan blocks #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a7124eb
Add more blocks
johndgiese May 22, 2019
87938af
Switch from FullLoader to SafeLoader
johndgiese May 22, 2019
66b8a50
Bump version
johndgiese May 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
73 changes: 49 additions & 24 deletions rdm/base/software_plan.md
View file
Open in desktop
Expand Up @@ -19,7 +19,7 @@ The primary purpose of this document is to help developers ensure {{ system.proj
[[:In order to assist auditors and regulators, we have included section references to {{ system.standard }} as well as occasional comments throughout this document. These references and comments are always placed inside square brackets, and they are not present in the software-developer version of the document. Other than these comments, the software-developer version is identical to the auditor version of this document.]]
{% endblock %}
# Overview

{% block definitions %}
## Definitions
[[:Most of these definitions are very similar to the {{ system.standard }} definitions, however, they have been simplified and clarified as appropriate for a better understanding by software developers.]]

Expand All @@ -38,19 +38,21 @@ Problem reports and change requests are both stored as GitHub issues. A GitHub
A **software requirement** is a particular function that the software must support, or some other constraint that the software must fulfill. Requirements describe the *what*, while specifications and designs describe the *how*.

{% block extra_definitions %}{% endblock %}

{% endblock %}
{% block development_life_cycle_model %}
## Development Life Cycle Model

{{ system.project_name }} will be developed using an agile software development life cycle model. The agile strategy develops the software system using a sequence of builds. Customer needs and software system requirements are partially defined up front, then are refined in each succeeding build [[62304:5.1.1; by "agile" we mean a combined evolutionary and incremental life cycle model]].

{% endblock %}
{% block roles_and_responsibilities %}
## Roles and Responsibilities

The activites described in this document are designed for a team composed of a project lead and one to eight software developers. One of the software developers shall be assigned the role of the project lead. The project lead, working on behalf of the manufacturer, is responsible for the safety and utility of the software system built by the team.

{# TODO: briefly discussion conviction that software developers are in the best position to perform risk analysis and documentation during development #}

At least one team member must be trained in risk management [[14971:3.3]].

{% endblock %}
{% block documents %}
## Related Documents

Expand All @@ -69,17 +71,17 @@ A **test record** describes a set of tests which were run, when, and by who. It
{% endblock %}
{%- block project_details %}{% endblock %}
{# TODO: split out the test plan and other sections of the project_details into more granular blocks #}

{% block activites %}
# Activities

This section of the software plan describes the various activities involved with software development, maintenance, risk management, problem resolution, and version control (also known, in regulatory lingo as "configuration management"). The relationship between the inputs and outputs of these activities are displayed in the following diagram and are fully described in the sub-sections below. Since we are using an agile development life cycle, activities may be performed before their inputs have settled and thus inputs and outputs may not be consistent between releases.

[[:This software plan does not explicitly separate the software development process, software maintenance process, configuration management process, problem resolution process, and software-related risk management because we are using an agile software development life cycle and thus the processes overlap with one another significantly. The activities described here fulfill 62304:5.1.1.a, 5.1.1.b, 5.1.6, 5.1.7, and 5.1.9.b as well as, software-related portions 14971:3.4.a, 3.4.b, 3.4.c, and 3.4.e]]

{% block activity_diagram %}
## Activity Diagram

![Overview of life-cycle processes](../images/lifecycle-processes.svg)

{% endblock %}
{% block activity_planning -%}
## Planning

Expand Down Expand Up @@ -116,7 +118,7 @@ Ensure that activity in the software plan specifies:
- output verification steps, if any
- which role should perform and verify the activity [[62304:5.1.6.a and 5.1.6.b]].
{%- endblock %}

{% block activity_requirements_analysis %}
## Requirements Analysis

**Input:** System requirements and risk controls
Expand All @@ -141,6 +143,8 @@ See [the appendices](#requirements-analysis) for additional information.
- don't contradict each other
- have unambiguous descriptions
- are stated in terms that permit establishment of test criteria and performance of tests to determine whether the test criteria have been met [[62304:5.2.6]].
{% endblock %}
{% block activity_architectural_design %}
{% if system.safety_class != 'A' %}
## Architectural Design

Expand All @@ -163,6 +167,8 @@ The initial architecture does not need to be complete, since code construction c
- is able to support interfaces between software items and between software items and hardware
- is such that the medical device architecture supports proper operation of any SOUP items [[62304:5.3.6]].
{% endif %}
{% endblock %}
{% block activity_risk_assessment %}
## Risk Assessment

[[:This activity is meant to fulfill sections 4, 5, 6.1, and 6.2 of 14971 with respect to software related risks]]
Expand Down Expand Up @@ -195,7 +201,8 @@ See the [appendices](#risk-management) for additional information.
- Ensure that the hazard, hazardous situation, and harms recorded for new risks appropriately follow their ISO14971 definitions.
- Ensure that the risk probability is justifiable.
- Ensure that the new risks listed are appropriate, and are not unnecessarily detailed to the point of not contributing to improved safety.

{% endblock %}
{% block activity_risk_control %}
## Risk Control

**Input:** Risk assessment
Expand All @@ -216,7 +223,8 @@ Create a change request for the risk control measure.

- Ensure that risks controls don't introduce larger risks than they mitigate [[14971: 6.6 and 62304:7.3.1, since risk control measures will be implemented as part of this activity]]
- As appropriate, ensure that the inherent safety by design is preferred over adding software or hardware risk control measures.

{% endblock %}
{% block activity_division_of_labor %}
## Division of Labor

**Input:** Design files
Expand All @@ -226,7 +234,8 @@ There are many ways to divide new requirements work into change requests. Chang
**Output:** Feature change requests

**Verification:** Not applicable to this activity

{% endblock %}
{% block activity_release_planning %}
## Release Planning

[[:This activity addresses 62304:6.3.1, since change requests resulting from maintenance and problem resolution are processed in the same manner in which risk control measures and feature change requests are.]]
Expand All @@ -249,7 +258,8 @@ Create change requests as appropriate.
**Output:** The set of change requests which should be implemented for the next release

**Verification:** Not applicable to this activity

{% endblock %}
{% block activity_detailed_design %}
{% if system.safety_class == 'C' %}
## Detailed Design

Expand All @@ -269,6 +279,8 @@ Once you have completed the detailed design, open a pull request and assign the
- implements system and software requirements
- is free from contradiction with the SDS [[62304:5.4.4]].
{% endif %}
{% endblock %}
{% block activity_unit_implementation_and_testing %}
## Unit Implementation and Testing

[[:This activity addresses 62304:5.5.1]]
Expand Down Expand Up @@ -336,7 +348,8 @@ If, as is occasionally appropriate, someone outside of the core development team
{%- if system.safety_class != 'C' %}
Occasionally, due to the absence of other reviewers or due to an internal testing deadline, it may be necessary to skip verification. When this occurs, the developer should justify why a review wasn't necessary within the pull request comments.
{% endif %}

{% endblock %}
{% block activity_integration %}
## Integration

{# TODO: address traceability from software items to software system tests; see 62304:5.1.1.c #}
Expand All @@ -348,7 +361,8 @@ Merge the approved git branch into the `master` git branch, correct any merge co
**Output:** Merged pull request

**Verification:** Not applicable to this activity

{% endblock %}
{% block activity_integration_and_system_testing %}
## Integration and System Testing

**Input:** Software system built using the changes from this release's change requests
Expand All @@ -370,7 +384,8 @@ Any test failures found during the formal release system testing shall be record
- any adverse trends have been reversed [[62304:9.7.b]].

[[:Note that we combine our integration and system testing into one activity. We presume that if our integration tests and system tests are passing, no new problems were introduced, per 62304:9.7.d]]

{% endblock %}
{% block activity_release %}
## Release

[[:This activity addresses 62304:6.3.2, since development releases and maintenance releases are treated equivalently]]
Expand All @@ -387,7 +402,7 @@ Archived releases shall be kept until there are no longer supported devices bein
[[:This section fulfills 62304:5.8.7; note that documentation and configuration items are archived automatically due to the fact that they are stored in Git]]

**Output:** An archived software release

{% block activity_release_verification %}
**Verification:** Ensure that

- all of the planned change requests have been implemented and integrated [[62304:5.6.2 and 9.7.c]]
Expand All @@ -398,17 +413,20 @@ Archived releases shall be kept until there are no longer supported devices bein
- the software design specification is accurate and up-to-date
- [integration and system testing activity](#integration-and-system-testing) has been completed after the last change request was integrated, and a test record has been written [[62304:5.8.1]]
- the Release History Document is up-to-date and none of the anomlies result in unacceptable risk [[62304:5.8.2, 5.8.3, and 5.8.4]]

{%- block activity_release_verification_extra %}{% endblock %}
{% endblock %}
{# When you edit the list of verification steps here, also update `init_files/documents/release_history.md` -#}

Record these verification steps in the release history document.

{# TODO: add details about 14971:7 and 8 #}

{% endblock %}
{% block activity_problem_analysis %}
## Problem Analysis

Feedback from users, internal testers, and software developers will be recorded in {{ system.feedback_location }} [[62304:6.1.a, 6.1.b and 6.2.1.1; details about where direct customer feedback is recorded and tracked is not handled here. It is assumed that other processes (e.g., perhaps part of the broader quality management system) will handle this. We also do not go into detail here regarding what criteria should be used to determine whether feedback is considered a problem, as required by 6.1.b]].

{% endblock %}
{% block activity_prepare_problem_report %}
## Prepare Problem Report

[[:This activity addresses 62304:6.2.1.2]]
Expand All @@ -430,7 +448,8 @@ When creating a new problem report, include in the description:
**Output:** The problem report

**Verification:** Not applicable to this activity

{% endblock %}
{% block activity_problem_investigation %}
## Problem Investigation

[[:This activity addresses 62304:6.1.d and 6.2.2]]
Expand All @@ -448,11 +467,13 @@ When creating a new problem report, include in the description:
**Output:** Details about the problem investigation documented in the problem report and either unapproved change requests or justification as to why change requests weren't necessary

**Verification:** Not applicable to this activity

{% endblock %}
{% endblock %}
{% block appendices %}
# Appendices

The subsections here provide guidance on following the software risk management, development, and maintenance activities.

{% block appendix_requirements_analysis %}
## Requirements Analysis

Writing software requirements is an art and a science; one must find balance between precision and usefulness.
Expand Down Expand Up @@ -515,7 +536,8 @@ l. Regulatory requirements
m. Risk control measures

Software requirements that implement risk controls should be tied to their originating risk control by tagging them with labels that match the risk control ids [[62304:5.1.1.c]].

{% endblock %}
{% block appendix_risk_management %}
## Risk Management

This subsection provides a brief introduction to risk management in the context of software development.
Expand Down Expand Up @@ -543,7 +565,8 @@ Software is not itself a hazard because it can not directly cause harm, but soft
{# TODO: discuss probabilities of software events #}

{# TODO: add details about the `risk.yml` file format #}

{% endblock %}
{% block appendix_soup %}
## SOUP

Information in the `soup.yaml` file may duplicate information found in other files (e.g., `requirements.txt` or `package.json`).
Expand All @@ -570,3 +593,5 @@ When reviewing open anomalies:
- If the list of known anomalies is large (e.g., more than 100), without prioritization, then sample the list as appropriate for the risk associated with the SOUP.
- When possible, focus the review on anomalies which affect portions of SOUP which are used by {{ system.project_name }}.
{% endif -%}
{% endblock %}
{% endblock %}
2 changes: 1 addition & 1 deletion rdm/tex.py
View file
Open in desktop
Expand Up @@ -37,7 +37,7 @@ def _extract_yaml_front_matter(raw_string):
front_matter_string = parts[1]
template_string = '---\n'.join(parts[2:])
try:
front_matter = yaml.load(front_matter_string, Loader=yaml.FullLoader)
front_matter = yaml.load(front_matter_string, Loader=yaml.SafeLoader)
except yaml.YAMLError as e:
raise ValueError('Invalid YAML front matter; improperly formatted YAML: {}'.format(e))
return template_string, front_matter
Expand Down
4 changes: 2 additions & 2 deletions rdm/util.py
View file
Open in desktop
Expand Up @@ -22,7 +22,7 @@ def represent_ordereddict(dumper, data):

def load_yaml(yml_path):
with open(yml_path) as yml_file:
return yaml.load(yml_file, Loader=yaml.FullLoader)
return yaml.load(yml_file, Loader=yaml.SafeLoader)


def write_yaml(data, yml_file):
Expand Down Expand Up @@ -73,7 +73,7 @@ def context_from_data_files(data_filenames):
with open(data_filename, 'r') as data_file:
data_string = data_file.read()
try:
data = yaml.load(data_string, Loader=yaml.FullLoader)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change eliminates the ability to have the yaml contain any custom objects we have imported. Is this necessary? From yaml/pyyaml#257 ...

We added a new loader class called FullLoader, and we made it the default for
load(). This class is almost as complete for serialization as
UnsafeLoader/Loader, but it avoids arbitrary code execution. We don't expect it
will break any code in the wild.

We still recommend that people choose SafeLoader for untrusted data, but
aribitrary code execution will no longer be possible using yaml.load() with
the default loader (FullLoader). FullLoader will instantiate objects of classes
that you have imported. Since object instantiation runs the class's constructor
code, that may be exploitable.

data = yaml.load(data_string, Loader=yaml.SafeLoader)
except yaml.YAMLError as e:
raise ValueError('"{}" contains invalid YAML: {}'.format(data_filename, e))
context[key] = data
Expand Down
2 changes: 1 addition & 1 deletion setup.py
View file
Open in desktop
Expand Up @@ -11,7 +11,7 @@

setup(
name='rdm',
version='0.4.0',
version='0.7.0',
description=description,
long_description=description,
url='https://github.com/innolitics/rdm',
Expand Down