diff --git a/documentation/regulatory/.gitignore b/documentation/regulatory/.gitignore new file mode 100644 index 0000000..d75f845 --- /dev/null +++ b/documentation/regulatory/.gitignore @@ -0,0 +1,2 @@ +tmp +release diff --git a/documentation/regulatory/Makefile b/documentation/regulatory/Makefile new file mode 100644 index 0000000..db489b1 --- /dev/null +++ b/documentation/regulatory/Makefile @@ -0,0 +1,42 @@ +SHELL := /bin/bash -o pipefail -e +.SUFFIXES: +.SECONDARY: +.DELETE_ON_ERROR: + +CONFIG := config.yml +DATA_FILES := $(wildcard data/*.yml) +SRC_MDS := $(wildcard documents/**/*.md documents/*.md) +RELEASE_MDS := $(patsubst documents/%.md,release/%.md,$(SRC_MDS)) +RELEASE_PDFS := $(patsubst documents/%.md,release/%.pdf,$(SRC_MDS)) +RELEASE_DOCS := $(patsubst documents/%.md,release/%.docx,$(SRC_MDS)) + +all: $(RELEASE_MDS) + +pdfs: $(RELEASE_PDFS) + +docs: $(RELEASE_DOCS) + +release/%.md: documents/%.md $(CONFIG) $(DATA_FILES) + @mkdir -p $(@D) + rdm render $< $(CONFIG) $(DATA_FILES) > $@ + +release/%.pdf: release/%.md pandoc_pdf.yml template.tex + @mkdir -p $(@D) + pandoc --defaults=./pandoc_pdf.yml $< -o $@ + +release/%.docx: release/%.md pandoc_docx.yml + @mkdir -p $(@D) + pandoc --defaults=./pandoc_docx.yml $< -o $@ + +# useful for debugging +release/%.tex: release/%.md pandoc_pdf.yml template.tex + @mkdir -p $(@D) + pandoc --defaults=./pandoc_pdf.yml -t latex $< -o $@ + +# Manually call recipe to pull down your development history +data/history.yml: + rdm pull $< > $@ + +.PHONY: +clean: + rm -rf tmp release diff --git a/documentation/regulatory/config.yml b/documentation/regulatory/config.yml new file mode 100644 index 0000000..2c7b4d1 --- /dev/null +++ b/documentation/regulatory/config.yml @@ -0,0 +1,11 @@ +md_extensions: + - 'rdm.md_extensions.SectionNumberExtension' + - 'rdm.md_extensions.VocabularyExtension' + #- 'rdm.md_extensions.AuditNoteExclusionExtension' + +# The repository location within the project management tool +repository: user/repository + +project_management_backend: 'rdm.project_management.GitHubIssueBackend' + +reviews_required: True diff --git a/documentation/regulatory/data/definitions.yml b/documentation/regulatory/data/definitions.yml new file mode 100644 index 0000000..fdea7ba --- /dev/null +++ b/documentation/regulatory/data/definitions.yml @@ -0,0 +1,19 @@ +Activity: A set of one or more interrelated or interacting tasks. An activity has an input, an output, and often an explicit verification task. Records of activity outputs must be available in case of an audit. +Software System: All of the software in the project. The software system is decomposed into **software items**. +Software Item: >- + A module within the software system which may further decomposed into smaller + software items. The **software system** is itself a software item, and thus + the software items for a hierarchy. See the software design specification for + a description of how the software system is decomposed into smaller software + items. +Software Unit: A software item which is not further subdivided. +SOUP: >- + **Software of unknown provenance**, also known as "off-the-shelf software", + is a **software item** that has not been developed for the purpose of being + incorporated into the medical device and for which adequate records of the + development processes are not available. +Problem Report: A record of actual or potential behavior of a software product that a user or other interested person believes to be unsafe, inappropriate for the intended use or contrary to specification. +Known Anomaly: A problem report that we do not plan on addressing. +Change Request: A documented specification of a change to be made to the software system. +Software Requirement: 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*. +Record: A special type of document that states the results achieved or provides evidence that activities were performed. Unlike other documents---such as this software plan---records are not usually revised after being approved. diff --git a/documentation/regulatory/data/device.yml b/documentation/regulatory/data/device.yml new file mode 100644 index 0000000..103c7a2 --- /dev/null +++ b/documentation/regulatory/data/device.yml @@ -0,0 +1,35 @@ +# This data file contains details about your medical device. + +# The trade name of the device +name: "Device Name" + +# The legal name of the device's manufacturer +manufacturer: "Manufacturer, Inc." + +# The current release number for the device +version: "v0.1.0" + +# What is the FDA's software Level of Concern? +# "Minor" - Failures or latent design flaws are unlikely to cause any injury to +# the patient or operator. +# "Moderate" - A failure or latent design flaw could directly +# result in minor in jury to the patient or operator. The level of concern +# is also Moderate if a failure or latent flaw could indirectly result in +# minor injury to the patient or operator through incorrect or delayed +# information or through the action of a care provider. +# "Major" - A failure or latent flaw could directly result in +# death or serious in jury to the patient or operator. The level of concern +# is also Major if a failure or latent flaw could indirectly result in death +# or serious injury of the patient or operator through incorrect or delayed +# information or through the action of a care provider. +level_of_concern: Moderate + +# What is the IEC62304 safety classification of the entire system? +# "A" - No injury or damage to health is possible +# "B" - Non-serious injury is possible +# "C" - Death or serious injury is possible +safety_class: B + +# Is this software part of a medical device or is it Software as a Medical +# Device (i.e., SaMD)? +samd: true diff --git a/documentation/regulatory/data/history.yml b/documentation/regulatory/data/history.yml new file mode 100644 index 0000000..9e1f191 --- /dev/null +++ b/documentation/regulatory/data/history.yml @@ -0,0 +1,35 @@ +change_requests: +- id: '1' + title: Feature Change Request + content: A description of the requested changes should go here. Usually, + this data is periodically pulled out of a separate project management tool, + such as github + is_problem_report: false + change_ids: + - '1' +- id: '2' + title: Problem Report + content: A problem report may or may not also be a change request. If the + reported problem doesn't require changes, then it is just a "known anomaly" + that won't be addressed. If it does require changes, it also acts as a + change request. + is_problem_report: true + change_ids: [] +changes: +- id: '1' + content: Implement Feature Request + approvals: + - id: '100' + reviewer: + name: David Giese + id: '400' + content: ' + - [x] Implements change request + - [x] Consistent with software system design + - [x] Documentation: N/A + - [x] Unit tests + - [x] Risk assessment: added appropriate risks + - [x] Integration tests: N/A' + authors: + - name: Yujan Shreshta + id: '401' diff --git a/documentation/regulatory/data/integration_test_record.yml b/documentation/regulatory/data/integration_test_record.yml new file mode 100644 index 0000000..76ccd6f --- /dev/null +++ b/documentation/regulatory/data/integration_test_record.yml @@ -0,0 +1,20 @@ +# rdm translate utility can be used to generate YANL files from gtest, xunit or qttest xml output files. +TestClass.TestName100: + message: null + name: TestClass.TestName1 + result: pass + req_ids: [SR-13, SR-14] +TestClass.TestName200: + message: "Assertion failed: 127 != 0" + name: TestClass.TestName1 + result: fail + req_ids: [SR-17] + note: 'It is okay that this test failed because of XYZ' +TestClass.TestName300: + message: null + name: TestClass.TestName1 + result: pass + req_ids: [SR-17] + + + diff --git a/documentation/regulatory/data/manual_tests.yml b/documentation/regulatory/data/manual_tests.yml new file mode 100644 index 0000000..171fce7 --- /dev/null +++ b/documentation/regulatory/data/manual_tests.yml @@ -0,0 +1,14 @@ +- name: ManualTest1 + steps: + - step: 5 + result: pass + req_ids: [SR-18] + - step: 6 + req_ids: [SR-19] + result: fail + note: 'Allowed because of XYZ' +- name: ManualTest2 + steps: + - step: 1 + result: pass + req_ids: [SR-11, SR-12] diff --git a/documentation/regulatory/data/predicate.yml b/documentation/regulatory/data/predicate.yml new file mode 100644 index 0000000..0cf1a89 --- /dev/null +++ b/documentation/regulatory/data/predicate.yml @@ -0,0 +1,20 @@ +# This data file contains details about your predicate device. +# It is only relevant if you're planning on filing a 510(k) with the US FDA. + +# The tradename of the predicate device +name: "Predicate Device Tradename" + +# The 510(k) number +number: "Kxxxxxx" + +# The legal manufacturer of the device +manufacturer: "Predicate Device Manufacturer" + +# The model number of the device +model: "Predicate Device Model Number" + +# The FDA product code +product_code: "XYZ" + +# The related FDA regulation number +regulation_number: "21 CFR XXX.XXXX" diff --git a/documentation/regulatory/data/requirements.yml b/documentation/regulatory/data/requirements.yml new file mode 100644 index 0000000..7ebe457 --- /dev/null +++ b/documentation/regulatory/data/requirements.yml @@ -0,0 +1,22 @@ +- id: r-1 + title: First Example Requirement + system_requirements: [SR-6] + description: A brief description of the requirement; should use the world "shall". If the software is a "software only device", then no "system_requirements" are necessary---you can remove these keys completely. They are only necessary for medical devices with a hardware component. + specifications: | + The specification should describe *how* the requirement is met. Thus, the requirement is the *what* and the specification is the *how*. + + Specifications are written using github-flavored markdown. +- id: r-2 + title: Second Example Requirement + system_requirements: [SR-6, SR-11] + description: Requirements describe what the software needs to do, and not how. + specifications: | + Another specification goes here. +- id: r-3-1 + title: Third Example Requirement Nested Id First Item + system_requirements: [SR-4] + description: Requirements should be verifiable (e.g., testable). +- id: r-3-2 + title: Fourth Example Requirement Nested Id Second Item + system_requirements: [SR-4, SR-7] + description: Requirements can be written using markdown. diff --git a/documentation/regulatory/data/risk.yml b/documentation/regulatory/data/risk.yml new file mode 100644 index 0000000..4010a3c --- /dev/null +++ b/documentation/regulatory/data/risk.yml @@ -0,0 +1,48 @@ +risk_levels: + - label: Low + description: Acceptable + - label: Medium + description: Investigate further risk reduction + - label: High + description: Unacceptable +risk_probability_levels: + - label: Low + description: Unlikely + - label: Medium + description: Somewhat likely + - label: High + description: Likely +risk_severity_levels: + - label: Negligible + description: Inconvenience or temporary discomfort + - label: Minor + description: Results in temporary injury or impairment not requiring professional medical intervention + - label: Serious + description: Results in injury or impairment requiring professional medical intervention + - label: Critical + description: Results in permanent impairment or life-threatening injury + - label: Catastrophic + description: Results in patient death +risk_acceptability_matrix: + - [Low, Low, Low, Low, Low] + - [Low, Low, Low, Low, Medium] + - [Low, Low, Low, Medium, Medium] + - [Low, Low, Medium, Medium, High] + - [Low, Medium, Medium, High, High] +risks: + - hazard: Incorrect information + software_item: Annotation Metric Calculator + events: | + - A software defect in the Annotation Metric Calculator causes the + size an annotated tumor to be significantly under-estimated + - The radiologist fails to notice the discrepancy + hazardous_situation: The oncologist is presented with incorrect tumor sizes + harm: An inappropriate therapy is given to the patient + severity: Catastrophic + probability: Low + control_measures: null + residual_severity: null + residual_probability: null + notes: Although it is not possible to estimate the probability of the + software defect occurring, it is unlikely that the radiologist would not + noticed the discrepancy. diff --git a/documentation/regulatory/data/soup.yml b/documentation/regulatory/data/soup.yml new file mode 100644 index 0000000..ad580c8 --- /dev/null +++ b/documentation/regulatory/data/soup.yml @@ -0,0 +1,13 @@ +- title: Example Camera SDK + manufacturer: Basler AG + version: "5.3.1" + purpose: | + To allow us to configure, control, and retrieve images from our cameras. + requirements: | + Linux kernel version 3.x or higher + anomaly_reference: https://example.url/pointing/to/issue/list +- title: FFTW + version: "3.3.5" + purpose: | + To calculate the Fast Fourier Transform. + anomaly_reference: https://github.com/FFTW/fftw3/issues diff --git a/documentation/regulatory/data/unit_test_record.yml b/documentation/regulatory/data/unit_test_record.yml new file mode 100644 index 0000000..61f4e56 --- /dev/null +++ b/documentation/regulatory/data/unit_test_record.yml @@ -0,0 +1,14 @@ +# rdm translate utility can be used to generate YANL files from gtest, xunit or qttest xml output files. +TestClass.TestName1: + message: null + name: TestClass.TestName1 + result: pass + req_ids: [SR-12] +TestClass.TestName2: + message: null + name: TestClass.TestName1 + result: fail + req_ids: [SR-12] + note: 'It is okay that this test failed because of XYZ' + + diff --git a/documentation/regulatory/data/versions.yml b/documentation/regulatory/data/versions.yml new file mode 100644 index 0000000..c1295ba --- /dev/null +++ b/documentation/regulatory/data/versions.yml @@ -0,0 +1,12 @@ +- date: 1-1-2040 + release_id: v1.0 + changes: + - Add major new feature X. + - Add major new feature Y. + - Several bug fixes related to ZZZ. +- date: 5-5-2039 + release_id: v0.1 + changes: + - Add major new feature A. + - Add major new feature B. + - Several bug fixes related to CDE. diff --git a/documentation/regulatory/data/workflow.yml b/documentation/regulatory/data/workflow.yml new file mode 100644 index 0000000..a5391bb --- /dev/null +++ b/documentation/regulatory/data/workflow.yml @@ -0,0 +1,15 @@ +# The IEC62304 standard version +version_of_62304: "IEC62304:2006+A1:2015" + +# The location where the system requirements are stored; only used if +# `device.samd` is false. +system_requirements_location: "SYSTEM REQUIREMENTS SOFTWARE" + +# The location where risk analysis outputs are stored +risk_management_file: 'RISK MANAGEMENT FILE LOCATION' + +# The location where user feedback is stored, e.g. "GitHub Issues". +feedback_location: "USER FEEDBACK LOCATION" + +# Your Git host (e.g., "GitHub", "GitLab", or "BitBucket") +git_host: "GitHub" diff --git a/documentation/regulatory/documents/architecture_design_chart.md b/documentation/regulatory/documents/architecture_design_chart.md new file mode 100644 index 0000000..22a981c --- /dev/null +++ b/documentation/regulatory/documents/architecture_design_chart.md @@ -0,0 +1,12 @@ +--- +id: ADC-001 +revision: 1 +title: Architecture Design Chart +--- +![CSC Logo](./images/CSC-logo.png) + +# Note + +Our architecture design chart is included within our Software Design Specification. + +[[:This is required by the FDAGeneralSoftwareGuidance]] diff --git a/documentation/regulatory/documents/hazard_analysis.md b/documentation/regulatory/documents/hazard_analysis.md new file mode 100644 index 0000000..9e66e3f --- /dev/null +++ b/documentation/regulatory/documents/hazard_analysis.md @@ -0,0 +1,20 @@ +--- +id: HA-001 +revision: 1 +title: Device Hazard Analysis +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +This document presents our hazard analysis for {{ device.name }}. + +[[FDA-CPSSCMD:device-hazard-analysis]] + +# Scope + +This document applies to {{ device.name }} release {{ device.version }}. + +# Hazard Analysis + +TODO: pull in risk analysis data and present it in a table here diff --git a/documentation/regulatory/documents/known_anomalies.md b/documentation/regulatory/documents/known_anomalies.md new file mode 100644 index 0000000..4b9d425 --- /dev/null +++ b/documentation/regulatory/documents/known_anomalies.md @@ -0,0 +1,12 @@ +--- +id: KNANOM-001 +revision: 1 +title: Known Anomalies +--- +![CSC Logo](./images/CSC-logo.png) + +# Note + +Our unresolved anomalies are included within our Release History. + +[[:This is required by the FDAGeneralSoftwareGuidance]] diff --git a/documentation/regulatory/documents/level_of_concern.md b/documentation/regulatory/documents/level_of_concern.md new file mode 100644 index 0000000..dae2d60 --- /dev/null +++ b/documentation/regulatory/documents/level_of_concern.md @@ -0,0 +1,94 @@ +--- +id: LOC-001 +revision: 1 +title: Level of Concern +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +This document states and justifies our Level of Concern for the software within {{ device.name }}. + +[[FDA-CPSSCMD:level-of-concern]] + +# Scope + +This document applies to {{ device.name }} release {{ device.version }}. + +# Level of Concern + +The Level of Concern for the software system within {{ device.name }} is **{{ device.level_of_concern }}**. + +# Justification for Stated Level of Concern + +TODO: Describe how you arrived at the stated Level of Concern. Below is a template for a device that has a minor Level of Concern, hence the "No" response for all of the questions. Be sure to read the questions and update the responses as appropriate. + +See the 2005 "Guidance for the Content of Premarket Submissions for Software Contained in Medical Devices" for details. + +We believe the software system inside {{ device.name }} has a {{ device.level_of_concern }} Level of Concern because ... + +ENDTODO + +## Role of the Software + +TODO: Describe the role of the software in causing, controlling, and/or mitigating hazards that could result in injury to the patient or the operator. + +## Major Level of Concern Key Questions + +When evaluating our Software Device's Level of Concern, we considered the Key Questions provided in [1]. Our answers to these key questions for Major Level of Concern Devices are presented below: + +**1. Does the Software Device qualify as Blood Establishment Computer Software?** + +No. + +**2. Is the Software Device intended to be used in combination with a drug or biologic?** + +No. + +**3. Is the Software Device an accessory to a medical device that has a Major Level of Concern?** + +No. + +**4. Prior to mitigation of hazards, could a failure of the Software Device result in death or serious injury, either to a patient or to a user of the device?** + +No. + +**a. Does the Software Device control a life supporting or life sustaining function?** + +No. + +**b. Does the Software Device control the delivery of potentially harmful energy that could result in death or serious injury, such as radiation treatment systems, defibrillators, and ablation generators?** + +No. + +**c. Does the Software Device control the delivery of treatment or therapy such that an error or malfunction could result in death or serious injury?** + +No. + +**d. Does the Software Device provide diagnostic information that directly drives a decision regarding treatment or therapy, such that if misapplied it could result in serious injury or death?** + +No. + +**e. Does the Software Device provide vital signs monitoring and alarms for potentially life threatening situations in which medical intervention is necessary?** + +No. + +## Moderate Level of Concern Key Questions + +When evaluating our Software Device's Level of Concern, we considered the Key Questions provided in [1]. Our answers to these key questions for Moderate Level of Concern Devices are presented below: + +**1. Is the Software Device an accessory to a medical device that has a Moderate Level of Concern?** + +No. + +**2. Prior to mitigation of hazards, could a failure of the Software Device result in Minor Injury, either to a patient or to a user of the device?** + +No. + +**3. Could a malfunction of, or a latent design flaw in, the Software Device lead to an erroneous diagnosis or a delay in delivery of appropriate medical care that would likely lead to Minor Injury? ** + +No. + +# References + +[1]: "Guidance for the Content of Premarket Submissions for Software Contained in Medical Devices", 2005. diff --git a/documentation/regulatory/documents/note_about_missing_requirements.md b/documentation/regulatory/documents/note_about_missing_requirements.md new file mode 100644 index 0000000..8d34d61 --- /dev/null +++ b/documentation/regulatory/documents/note_about_missing_requirements.md @@ -0,0 +1,45 @@ +--- +id: NOTE-001 +revision: 1 +title: Note About Missing Requirements +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +This document lists IEC62304 regulatory requirements that aren't addressed by the other documents in this folder. + +It is a record of items that must be handled elsewhere to be IEC62304 compliant.It isn't meant to be given to regulatory bodies, and can be deleted if it is no longer used. + +# Scope + +This document applies to {{ device.name }} release {{ device.version }}. + +# Quality Management System + +The IEC62304 activities are meant to be part of a quality management system [[62304:4.1]]. The quality management system requires several activities that aren't included here. + +Feedback and complaints must be gathered and incorporated into release planning [[14971:9 and 14971:3.4.f]]. These activities are not included here. + +# Risk Management + +A few risk management tasks are not included. We hope to include all of these in a future release. + +Personnel must be qualified for the tasks they perform. In particular, risk management tasks must be performed by people with experience in those tasks [[14971:3.3 and 13485:6.2]]. + +The risk management report is not currently included in an RDM activity [[14971:8.a, 14971:8.b, 14971:8.c]]. + +Residual risk evaluation [[14971:6.4]], risk/benefit analysis [[14971:6.5]], risk control completeness [[14971:6.7]], and the evaluation of residual risk acceptability [[14971:7]] are not currently addressed. + +# 62304 Class C Software + +A few requirements for developing class C software aren't addressed yet: + +- 62304:5.5.4.a Additional Software Unit Acceptance Criteria: proper event sequence +- 62304:5.5.4.b Additional Software Unit Acceptance Criteria: data and control flow +- 62304:5.5.4.c Additional Software Unit Acceptance Criteria: planned resource allocation +- 62304:5.5.4.d Additional Software Unit Acceptance Criteria: fault handling +- 62304:5.5.4.e Additional Software Unit Acceptance Criteria: initialization of variables +- 62304:5.5.4.f Additional Software Unit Acceptance Criteria: self-diagnostics +- 62304:5.5.4.g Additional Software Unit Acceptance Criteria: memory management and memory overflows +- 62304:5.5.4.h Additional Software Unit Acceptance Criteria: boundary conditions diff --git a/documentation/regulatory/documents/release_history.md b/documentation/regulatory/documents/release_history.md new file mode 100644 index 0000000..4d2155e --- /dev/null +++ b/documentation/regulatory/documents/release_history.md @@ -0,0 +1,89 @@ +--- +id: RELEASE-001 +title: Release History +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +The purpose of this document is to list the change requests that were implemented within the current release. It also includes approval of the change requests and the verification of the implemented changes. Finally, it lists the problem reports that were addressed in the release as well as any outstanding problem reports (i.e., known anomalies). + +# Scope + +This document applies to {{ device.name }}, and includes changes made in release {{ device.version }}. + +# History + +This section provides a summarized history of software revisions generated during the course of product development. + +{% for version in versions | reverse %} +## {{ device.name }} {{ version.release_id }} ({% if version.date %}{{ version.date }}{% else %}in progress{% endif %}) +{% for change in version.changes or [] %} +- {{ change }} +{%- endfor %} +{%- endfor %} + +Testing was performed against TODO: add version. + +# Change Requests + +This section includes a list of change requests and their associated changes, which were implemented for Release {{ device.version }} of {{ device.name }}. + +{% for cr in history.change_requests|rejectattr('is_problem_report') %} +## {{ cr.title }} + +**Identifier:** {% if cr.url is defined %}[{{ cr.id }}]({{ cr.url }}){% else %}{{ cr.id }}{% endif %} +{% if cr.content is defined and cr.content %} +**Description:** + +{{ cr.content }} +{% endif %} +{% for c in cr.change_ids|join_to(history.changes) %} +**Implemented Change {% if c.url is defined %}[{{ c.id }}]({{ c.url }}){% else %}{{ c.id }}{% endif %}:** + +Implemented by {{ c.authors[0].name }} +{%- if c.approvals %}, verified by {{ c.approvals[-1].reviewer.name }}{% endif %}. +{% if c.content is defined %} +{{ c.content }} +{% endif %} +{% endfor %} +{% endfor %} + +# Problem Reports + +This section includes a list of problem reports which were addressed for release {{ device.version }} of {{ device.name }}. + +{% for cr in history.change_requests|selectattr('is_problem_report')|selectattr('change_ids') %} +## {{ cr.title }} + +**Identifier:** {% if cr.url is defined %}[{{ cr.id }}]({{ cr.url }}){% else %}{{ cr.id }}{% endif %} + +{# problem reports require a description, unlike normal change requests #} +**Description:** + +{{ cr.content }} +{% for c in cr.change_ids|join_to(history.changes) %} +**Implemented Change {% if c.url is defined %}[{{ c.id }}]({{ c.url }}){% else %}{{ c.id }}{% endif %}:** + +Implemented by {{ c.authors[0].name }} +{%- if c.approvals %}, verified by {{ c.approvals[-1].reviewer.name }}{% endif %}. +{% if c.content is defined %} +{{ c.content }} +{% endif %} +{% endfor %} +{% endfor %} + +# Known Anomalies + +This section includes a list of outstanding problem reports (i.e., known anomalies). Each problem report should include the rationale why no changes were required. + +{% for cr in history.change_requests|selectattr('is_problem_report')|rejectattr('change_ids') %} +## {{ cr.title }} + +**Identifier:** {% if cr.url is defined %}[{{ cr.id }}]({{ cr.url }}){% else %}{{ cr.id }}{% endif %} + +{# problem reports require a description #} +**Description:** + +{{ cr.content }} +{% endfor %} diff --git a/documentation/regulatory/documents/release_record.md b/documentation/regulatory/documents/release_record.md new file mode 100644 index 0000000..f75aacc --- /dev/null +++ b/documentation/regulatory/documents/release_record.md @@ -0,0 +1,29 @@ +--- +id: RELEASEREC-001 +title: Software Release Record +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +The purpose of this document is to provide a record of the verification steps for teh software release activity, as performed for {{ device.name }}. + +# Scope + +This document applies to {{ device.name }} release {{ device.version }}. + +# Release Verification + +TODO fill in this list from the release verification activity + +I, PROJECT LEAD'S NAME, verify the following: + +- [ ] all of the planned change requests have been implemented and integrated +- [ ] the outputs of each activity are in a consistent state +- [ ] the unit tests adequately verify the software units +- [ ] the integration tests adequately verify the software units +- [ ] all software requirements have been tested or otherwise verified +- [ ] the software design specification is accurate and up-to-date +- [ ] integration and system testing activity has been completed after the last change request was integrated, and a test record has been written and linked to here +- [ ] none of the known anomlies result in unacceptable risk +- [ ] the test results meet the required pass/fail criteria listed in Testing Plan section of the Software Plan document. diff --git a/documentation/regulatory/documents/software_description.md b/documentation/regulatory/documents/software_description.md new file mode 100644 index 0000000..e813128 --- /dev/null +++ b/documentation/regulatory/documents/software_description.md @@ -0,0 +1,12 @@ +--- +id: SD-001 +revision: 1 +title: Software Description +--- +![CSC Logo](./images/CSC-logo.png) + +# Note + +Our software description is included within the Software Design Specification. + +[[:This is required by the FDAGeneralSoftwareGuidance]] diff --git a/documentation/regulatory/documents/software_design_specification.md b/documentation/regulatory/documents/software_design_specification.md new file mode 100644 index 0000000..8824884 --- /dev/null +++ b/documentation/regulatory/documents/software_design_specification.md @@ -0,0 +1,135 @@ +--- +id: SDS-001 +revision: 1 +title: Software Design Specification +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +This document describes *how* {{ device.name }} shall fulfill the requirements described in the software requirements specification. It discusses the computation hardware the software will be expected run on, the software system's architecture, functional specifications associated with each software requirement, and user interface mockups. + +It is written primarily for engineers working on {{ device.name }}, who have the source code available, in addition to this document. + +[[The legacy Software option of 62304:4.4 is not in use here.]] + +[[FDA-CPSSCMD:sds]] + +# Scope + +This document applies to {{ device.name }} release {{ device.version }}. + +# Definitions + +The **Food and Drug Administration (FDA)** is a United State government agency responsible for protecting the public health by ensuring the safety, efficacy, and security of human and veterinary drugs, biological products, and medical devices. + +The **Health Insurance Portability and Accountability Act** (HIPAA) is a United States law designed to provide privacy standards to protect patients' medical records and other health information provided to health plans, doctors, hospitals and other healthcare providers. + +**Protected Health Information** (PHI) means individually identifiable information that is created by {{ device.name }} and relates to the past, present, or future physical or mental health or condition of any individual, the provision of health care to an individual, or the past, present, or future payment for the provision of health care to an individual. + +**UI** is an acronym for user interface. + +# Software Description + +[[FDA-CPSSCMD:software-description]] + +TODO: Fill in the software description. Usually it should the programming language, hardware platform, operating system (if applicable), and any SOUP. + +# Architecture Design Chart + +TODO: Add a block diagram showing a detailed depiction of functional units and software items. You may also want to include state diagrams as well as flow charts [[FDA-CPSSCMD:architecture-design-chart]] + +# Software Items + +## Software Item A + +## Software Item B + +# SOUP Software Items + +This section enumerates the SOUP software items present within {{ device.name }}. + +{% for s in soup %} +## {{ s.title }} + +**Manufacturer:** +{% if s.manufacturer is defined %} +{{ s.manufacturer }} +{% else %} +SOUP was developed collaboratively by the free open-source software community, and does not have a manufacturer in the traditional sense. +{% endif %} +**Version:** + +`{{ s.version }}` +{% if device.safety_class != "A" %} +**Functional and Performance Requirements:** + +{{ s.purpose }} + +**Hardware & Software Requirements:** +{% if s.requirements is defined %} +{{ s.requirements }} +{% else %} +No noteworthy software or hardware requirements. +{% endif %} +**Known Anomalies:** +{% if s.anomaly_reference is not defined %} +Known anomaly list is not available. +{% else %} +{% if s.relevant_anomalies is not defined %} +No anomalies found that would result in incorrect behaviour for {{ device.name }} leading to a hazardous situation. +{% else %} +{{ s.anomalies }} +{% endif %} +**Open Anomaly List (Reference Only):** + +`{{ s.anomaly_reference }}` +{%- endif %} +{%- endif %} +{% endfor %} + +# Functional Specifications +{% for requirement in requirements %} +## {{ requirement.title }} + +*Requirement ID:* {{ requirement.id }} + +*Requirement:* {{ requirement.description }} +{% if 'specifications' in requirement %} + +*Functional Specifications:* +{{ requirement.specifications }} +{%- endif %} +{%- endfor %} + +# User Interface Mockups + +TODO: + +If you have user interface mockups, this is a good place to put them. One strategy is to include a sub-section for each screen, along with its own image file. Here are some examples: + +## Screen One (PNG) + +Use something like: `![Screen One](./images/uimockups/example-ui-mockup-001.png)` + +Which produces: + +![Screen One](./images/uimockups/example-ui-mockup-001.png) + +## Screen Two (JPG) + +Use something like: `![Screen Two](./images/uimockups/example-ui-mockup-002.jpg)` + +Which produces: + +![Screen Two](./images/uimockups/example-ui-mockup-002.jpg) + +## Screen Three (PNG Online) + +Use something like: `![Screen Three](https://github.com/innolitics/rdm/raw/a29fed650e55b376157cebe8843b087209a0b92a/rdm/init_files/images/uimockups/example-ui-mockup-001.png)` + +Which produces: + +![Screen Three](https://github.com/innolitics/rdm/raw/a29fed650e55b376157cebe8843b087209a0b92a/rdm/init_files/images/uimockups/example-ui-mockup-001.png) + +ENDTODO diff --git a/documentation/regulatory/documents/software_plan.md b/documentation/regulatory/documents/software_plan.md new file mode 100644 index 0000000..f85338b --- /dev/null +++ b/documentation/regulatory/documents/software_plan.md @@ -0,0 +1,623 @@ +--- +id: PLAN-001 +revision: 1 +title: Software Plan +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +This document describes a set of activities which will be used during software risk management, development, and maintenance of {{ device.name }}. It is written primarily for software developers. + +{{ device.name }} is assigned a Class {{ device.safety_class }} software safety class, which means {% if device.safety_class == "A" %}no injury or damage to health{% elif device.safety_class == "B" %}non-serious injury{% else %}death or serious injury{% endif %} could occur if the software fails [[62304:4.3.a]]. See {{ workflow.risk_management_file }} for details. All of the software items that compose the software system are also presumed to have the same Class {{ device.safety_class }} safety class [[62304:4.3.c 62304:4.3.d 62304:4.3.d 62304:4.3.e 62304:4.3.f 62304:4.3.g]]. The primary purpose of this document is to help developers ensure {{ device.name }} is safe and useful while also allowing developers to be productive. The secondary purpose is to comply with {{ workflow.version_of_62304 }}. + +[[:In order to assist auditors and regulators, we have included section references to {{ workflow.version_of_62304 }} 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.]] + +[[FDA-CPSSCMD:dev-environment]] + +# Overview + +## Definitions + +[[:Most of these definitions are very similar to the {{ workflow.version_of_62304 }} definitions, however, they have been modified as appropriate for a better understanding by software developers.]] + +{# TODO: update our first-pass rdm extension so that we can only include +phrases that occur in this document #} + +{% for word, definition in definitions.items()|sort %} +**{{ word }}** {{ definition }} +{% endfor %} + +## Development Life Cycle Model + +{{ device.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]]. + +## Roles and Responsibilities + +The activities 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:4.3]]. + +## Related Documents + +[[:This section fulfills 62304:5.1.8.a, 62304:5.1.8.b, and 62304:5.1.8.c]] + +The **level of concern** document is written by the project lead, in conjunction with the manufacturer, up front. Its purpose is to help guide the risk analysis and inform the FDA. It may be updated as part of [risk assessment activity](#risk-assessment). It is reviewed by the project lead during the [release activity](#release). + +The **software description** is not a separate document, but is included within the SDS. + +The **software requirements specification** (or **SRS**) describes what the software needs to accomplish. It is largely written by the project lead during the [requirements analysis activity](#requirements-analysis), and is reviewed by the project lead during the [release activity](#release). Software developers may clarify and extend the document slightly during the [unit implementation and testing activity](#unit-implementation-and-testing). + +The **software architecture chart** is not a separate document, but is included within the SDS. + +The **software design specification** (or **SDS**) describes how the software accomplishes what the SRS requires. A significant portion is written by the project lead during the [architectural design activity](#architectual-design), but many details and specifics are added by software developers during the [unit implementation and testing activity](#unit-implementation-and-testing). It is reviewed for consistency by the project lead during the [release activity](#release). + +A **release history** includes a list of change requests and problem reports addressed within a release. It also includes a record of the implemented changes and their verification and a list of known anomalies. The content of the document is slowly built up by software developers during the [unit implementation and testing activity](#unit-implementation-and-testing). It is reviewed by the project lead during the [release activity](#release). + +A **test record** describes a set of tests which were run, when, and by who. It also must include enough details to reproduce the testing setup. + +A **release record** describes the verifications steps performed by the project lead during the [release activity](#release). + +## Development Standards + +TODO: The project lead should keep an up-to-date list of development standards here (e.g., PEP8 on a Python project). + +If the software system's safety classification is not level C (the highest), you may delete this section. + +[[:This section fulfills 62304:5.1.4.a]] + +## Development Methods + +[[62304:5.1.4.b]] + +TODO: The project lead should keep an up-to-date list of development methods here (e.g., Test Driven Development) if relevant. + +If the software system's safety classification is not level C (the highest), you may delete this section. + +## Development Tools + +[[62304:5.1.4.c]] + +TODO: The project lead should keep an up-to-date list of development tools here, such as linters and versions. + +If the software system's safety classification is not level C (the highest), you may delete this section. + +To the extent possible, checking against these standards should be performed in an automated fashion (e.g., using a linter which is run on a Git-commit hook) [[62304:5.1.4]]. + +## Testing Plan + +[[62304:5.5.2]] + +All final tests must include the Git hash or other objective reference that can be used to identify the exact software tested [[62304:5.1.11]]. + +TODO: Write out a testing plan for {{ device.name }}. + +This plan should include a pass/fail criteria for the entire test suite. E.g., you require that all unit tests pass and that all integration tests pass or the cause of the failure is understood and justified [[62304:5.7.1.a]] + +## Risk Management + +The Risk Assessment, Risk Control and other activities below are intended to meet ISO 14971 risk management standard [[62304:4.2 14971:3.1 14971:3.2]]. + +# 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. [[Note that tasks are presented within each activity, although we do not explicitly demarcate them.]] + +[[: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:4.2 62304:5.1.1.a, 62304:5.1.1.b, 62304:5.1.6, 62304:5.1.7, and 62304:5.1.9.b as well as, software-related portions 14971:3.4.a, 14971:3.4.b, 14971:3.4.c, 14971:3.4.e, and 14971:3.5]] + +## Activity Diagram + +![Overview of life-cycle processes](./images/lifecycle-processes.png) + +## Planning + +**Input:** User needs, system requirements, and risk controls + +Setup a Git repository on {{ workflow.git_host }}. All software activity outputs will be stored in this Git repository, the associated {{ workflow.git_host }} issues, or the associated {{ workflow.git_host }} pull requests, unless explicitly noted otherwise [[62304:5.1.1.b]]. Problem reports and change requests are stored as {{ workflow.git_host }} issues. A {{ workflow.git_host }} issue tagged with the `bug` label is a problem report. If a problem report outlines a set of requested changes, then it can simultaneously act as a change request. {{ workflow.git_host }} issues tagged with the `obsolete` label are ignored. + +The software developers working on the project are responsible for keeping all software activity outputs within version control at the times specified in the activity descriptions [[62304:5.1.9.c, 62304:5.1.9.d, and 62304:5.1.9.e]]. + +[[:Note that we do not explicitly use the term "software configuration management" since many developers will be unfamiliar with the term, and instead we use the term "version control." Git is a version control system that makes it simple to track and record the history of every file it contains in a precise and controller manner. The requirements listed in sections 62304:5.1.9.a, 62304:5.1.11, 62304:8.1.1, 62304:8.1.3, 62304:8.3, and 62304:9.5 are fulfilled by our use of Git and {{ workflow.git_host }}. Also note that this setup implies that all activity outputs that are stored in the Git repository, {{ workflow.git_host }} issues, or {{ workflow.git_host }} pull requests are configuration items. Furthermore, the version of every configuration item comprising the software system configuration is stored in the Git repository for the entire history of the project. Each activity describes the configuration items in more detail.]] + +In the Software Design Specification, record details about the project's build process, including tool versions, environment variables, etc. [[62304:5.1.10 and 62304:5.8.5]]. Also document how the software can be reliably delivered to the point of use without corruption or unauthorized change [[62304:5.8.8]]. + +Search through this document, and the other documents in this set of templates, for the text "TODO". Follow the instructions next to the "TODO" sections. Once you are done you may delete the instructions. Note that longer instructions may be demarcated with "ENDTODO". + +Keep this planning document up to date as the project commences [[62304:5.1.2]]. + +In conjunction with the manufacturer's management, review and update as appropriate the: + +- qualitative risk severity categories +- qualitative risk probability categories +- qualitative risk levels + +contained within {{ workflow.risk_management_file }} [[14971:3.4.d, 14971:D.3, 14971:D.4, 14971:D.8]]. + +**Output:** The markdown version of this plan document and the Git repository hosted on {{ workflow.git_host }}. + +**Verification:** + +Review the document for typos our outdated information. + +Ensure that activity in the software plan specifies: + +- the activity inputs +- the activity outputs +- output verification steps, if any +- which role should perform and verify the activity [[62304:5.1.6.a and 62304:5.1.6.b]]. + +## Requirements Analysis + +**Input:** User needs, system requirements, and risk controls + +{% if not device.samd -%} +Systems requirements are stored in {{ workflow.system_requirements_location }}. Each system requirement must have a unique identifier so that we can trace software requirements back to the system requirements they fulfill [[62304:5.1.3.a 62304:5.1.3.b]]. +{% else %} +This project, being software as a medical device, has no system requirements [[62304:5.1.3.a 62304:5.1.3.b 62304:5.2.6.a 62304:5.2.6.f]]. +{%- endif %} + +Important software requirements should be enumerated at the start of the project [[62304:5.2.1]].{% if not device.samd %} Software requirements must be tied to one or more originating system requirements via the system requirement's ids [[62304:5.1.1.c]]. If a software requirement can not be tied back to any system requirements, new system requirements should be added.{% endif %} + +When software requirements are added or changed, re-evaluate the medical device risk analysis [[62304:5.2.4]] and ensure that existing software requirements{% if not device.samd %}, and system requirements,{% endif %} are re-evaluated and updated as appropriate [[62304:5.2.5]]. + +See [the appendices](#requirements-analysis) for additional information. + +**Output:** Software requirements, Git + +**Verification:** Ensure software requirements: +{% if not device.samd %} +- implement system requirements and are labeled with system requirement ids [[62304:5.2.6.a 62304:5.2.6.f]] +{%- endif %} +- implement risk controls +- don't contradict each other [[62304:5.2.6.b]] +- have unambiguous descriptions [[62304:5.2.6.c]] +- each has a unique identifier [[62304:5.2.6.e]] +- 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.d]]. + +{% if device.safety_class != 'A' %} + +## Architectural Design + +**Input:** Software requirements + +Develop an initial software system architecture and document it in the SDS [[62304:5.3.1]]. The SDS should describe how the software system is divided into a hierarchy of software items [[62304:5.4.1]]. Software units are often thought of as being a single function or module, but this is not always appropriate. + +Show the software and hardware interfaces between the software items and external software [[62304:5.3.2]]. Prefer block diagrams and flow charts to textual descriptions, and include these diagrams in the SDS. Indicate which software items are SOUP. + +{% if device.safety_class == 'C' %} +Identify any segregation between software items that is essential to risk control, and state how to ensure that the segregation is effective. For example, one may segregate software items by running them on different processors [[62304:5.3.5]]. +{% endif %} +The initial architecture does not need to be complete, since code construction can guide architectural decisions. However, it is worth spending a significant amount of time on the initial architecture. Once development commences (i.e., the [unit implementation and testing activity](#unit-implementation-and-testing)), update the SDS as the architecture is refined. + +**Output:** SDS + +**Verification:** Ensure software architecture documented in the SDS: + +- implements system and software requirements [[62304:5.3.6.a]]. +- is able to support interfaces between software items and between software items and hardware [[62304:5.3.6.b]]. +- is such that the medical device architecture supports proper operation of any SOUP items [[62304:5.3.6.c]]. +{% endif %} + +## Risk Assessment + +[[:This activity is meant to fulfill sections 14971:4.1.a, 14971:4.1.b, 14971:4.1.c, 14971:4.2 + 14971:5, 14971:6.1, and 14971:6.2 of 14971 with respect to software related risks]] + +**Input:** Software design specification + +Begin by identifying known and forseeably hazards associated with{% if device.samd %} how the software is intended to be used within medical practice{% else %} the device{% endif %} [[14971:4.3]]. It is frequently necessary to consult with a clinical expert to understand and identify hazards in their clinical context. + +Next, identify which software items could cause hazardous situations [[62304:7.1.1 62304:7.3.3.a]], and list them, along with the forseeably causes [[62304:7.3.3.b]]. Consider: + +- whether requirements are appropriate and are meeting the needs of users +- incorrect or incomplete specifications of functionality [[62304:7.1.2.a]] +- software defects in the software item [[62304:7.1.2.b]] +- failure or unexpected results from SOUP [[62304:7.1.2.c]] +- how hardware failures or software defects in other items could result in unpredictable operation [[62304:7.1.2.d]] +- reasonably forseeably misuse by users [[62304:7.1.2.e]] +- the list of causes in Annex B of IEC80002-1:2009 [[62304:5.1.12.a 62304:5.1.12.b]] + +Include the sequences of events that could result in the hazardous situation [[62304:7.1.5 ]]. +If failure or unexpected results from SOUP is a potential cause contributing to a hazardous situation, review the list of anomalies for the SOUP (if any) for known anomalies relevant to this hazardous situation [[62304:7.1.3]]. + +Record the identified hazards, causes, hazardous situations, and harms in {{ workflow.risk_management_file }} as an individual risk [[62304:7.1.4 and 62304:9.5]]. + +Finally, estimate the severity and probability of each risk and record this as well [[14971:4.4]]. + +See the [appendices](#risk-management) for additional information. + +**Output:** Risk assessment + +**Verification:** + +- 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. + +## Risk Control + +**Input:** Risk assessment + +Evaluate unmitigated risks listed in {{ workflow.risk_management_file }} [[14971:5]]. +{# TODO: for now, evaluating risks based on their probability and severity is a manual process. This should be automated with a tool sometime in the near future #} +{# TODO: incorporate residual risk evaluation [[14971:6.4]] and risk/benefit analysis [[14971:6.5]] #} +If any of the risks require reduction, then identify appropriate risk control measures. Consider risk control measure options, in the following order: + +1. inherent safety by design (i.e., refactoring or architecting away the risks, or even removing requirements) +2. adding software{% if not device.samd %} or hardware{% endif %} +3. providing information to the user in the form of documentation or user interface elements---these should be avoided as much as possible. + +Create a change request for the risk control measure [[14971:6.3 62304:7.2.1 62304:7.3.3.c]]. + +**Output:** Risk control related change requests + +**Verification:** + +- Ensure that risks controls don't introduce larger risks than they mitigate [[14971:6.6.a, 14971:6.6.b 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. + +{# Add activity to ensure completeness of risk control per 14971:6.7 #} + +## Division of Labor + +**Input:** Design files + +All work on the software project should occur in response to approved change requests [[62304:8.2.1]]. There are many ways to divide new requirements work into change requests. Change requests associated with requirements which will be implemented soon may be split into smaller change requests, while requirements which may not be worked on for several months can be captured in a single large change request. + +**Output:** Feature change requests + +**Verification:** Not applicable to this activity + +## 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. Note that some releases are only meant for tracking development. The first commercial release is typically v1.0.]] +]] + +**Input:** Feature and problem fix change requests + +To organize and prioritize the development work, change requests are assigned to {{ workflow.git_host }} milestones. Change requests that have not yet been assigned to a {{ workflow.git_host }} milestone have not yet been approved, and should not be worked on [[62304:8.2.1, 62304:6.2.4]]. + +Once a change request is assigned to a milestone, it has been "approved" and may be worked on by a developer. The project lead will then assign developers to change requests to divide up the work. Software developers may also assign themselves to change requests, so long as it is not assigned to another developer and they don't have other outstanding tickets they can work on. + +The project lead should coordinate with the business owner regarding which change requests to include in a release. When planning a release: + +- Consider outstanding problem reports [[62304:9.4]]. +- Look through historical problem reports and attempt to identify any adverse trends. For example, some software items may have many problem reports associated with them [[62304:9.6 and 14971:9.a]] + or may have new or revised standards [[14971:9.b]]. +- Review {{ workflow.risk_management_file }} for risk control measures that have not been implemented [[62304:7.3.1 and 62304:7.2.2.c]]. +- Review `soup.yml`. Look for SOUP which has become obsolete, SOUP which should be upgraded, and for known anomalies in published anomalies lists as appropriate [[62304:6.1.f]]. See [the appendices](#SOUP) for additional details. + +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 + +{% if device.safety_class == 'C' %} + +## Detailed Design + +**Input:** SDS + +Begin a new Git branch, as discussed in the [unit implementation and testing activity](#unit-implementation-and-testing), but before implementing the change request, document a detailed design either within the SDS or as code comments, as appropriate, for each new software item [[62304:5.4.2]]. These detailed designs should be stored as closely as possible to their corresponding source files. As appropriate, write out function signatures for the essential procedures, functions, classes, and/or modules involved with the change request. + +Detailed designs for interfaces between software items and external components (hardware or software) should be included as appropriate [[62304:5.4.3]]. + +Once you have completed the detailed design, open a pull request and assign the project lead to review the design. + +**Output:** Software item designs + +**Verification:** Ensure software requirements: + +- is not more complicated than it needs to be to meet the requirements +- implements system and software requirements [[62304:5.4.4.a]] +- is free from contradiction with the SDS [[62304:5.4.4.b]]. +{% endif %} + +## Unit Implementation and Testing + +[[:This activity addresses 62304:5.5.1]] + +**Input:** {% if device.safety_class == 'C' %}Detailed software item designs{% else %}SDS{% endif %} and software requirements + +Create a new Git branch with a name that includes the change request number (e.g., `104-short-description`). Commit your code changes to this branch and push periodically [[62304:5.1.1.d, 62304:6.1.e and 62304:8.2.2]]. Commit messages should: + +- explain why the current changes are being made, as appropriate +- reference the change request that prompted the changes (the `rdm hooks` command can streamline including these references). + +During development, as appropriate: + +{% if device.safety_class != 'C' -%} +- Write specifications for new software items in the SDS. +- Update the software architecture diagrams.{% endif %} +- Analyze how this change request effects the entire software system, and consider whether any software items should be refactored or reused [[62304:6.2.3]]. +- Consider whether any external systems that the software system interfaces with may be affected [[62304:6.2.3]]. +- If software has been released, consider whether any existing data needs to be migrated. +- Write unit tests and new integration tests. +- If SOUP was added, removed, or changed, update the `soup.yaml` file (see the [appendices](#SOUP) for details). +- If the change request includes risk control measures, record the risk control measures in {{ workflow.risk_management_file }} along with the residual risk. Also add new software requirements for the risk control measure and record the software requirement id along with the risk [[14971:6.2 and 62304:7.2.2.a]]. +- Perform the [Risk Assessment](#risk-assessment) [[14971:6.6]] and [Risk Control](#risk-control) Activities on any software items (including SOUP) which were are added or modified [[62304:7.4.1.a]], including new risk control measures[[62304:7.4.1.b, since they may have introduced new risks [[62304:6.1.c, 62304:7.4 62304:7.3.1, 62304:7.4.3 since risk control measures will be implemented as part of this activity]] or impact on existing risk control measures [[62304:7.4.2]]. + +When work on a change branch is nearing completion, a pull request should be created for this branch. A brief summary of the changes should be included in the pull request description. These comments will be included in the final release history. The description should also mention whether risk assessments were performed, or why not, and if tests were not required, why not. + +**Output:** Code and documentation changes, stored in un-merged Git branches with corresponding approved pull requests + +**Verification:** Code review by at least on other developer. + +Code review should ensure the code changes made in the Git branch: + +- implements the associated change request +- is consistent with the {% if device.safety_class == 'C' %}related detailed designs{% else %}software system design{% endif %} +{%- if device.safety_class == "C" %} +- follows the project's software standards +{%- endif %} +- includes unit tests or justifies why they are not necessary +- any risk assessments are reasonable +- is covered by existing integration tests or includes a new integration test [[62304:5.5.5 and 62304:8.2.3]]. + +The developer performing the review should create a {{ workflow.git_host }} review and record their notes there. If any changes are requested, address them and re-submit the review once they have been addressed. The reviewer must approve the pull request from within the {{ workflow.git_host }} user interface [[62304:8.2.4.c]]. Use the following set of acceptance criteria for your reviews [[62304:5.5.3]]: + +``` +- [x] Documents and implements software requirements +- [x] Is consistent with the software system design +- [ ] Code construction follows the project standards +- [ ] Unit, integration, or manual tests are updated +- [ ] New risks have been recorded +``` + +{%- if device.safety_class != 'C' %} +This detailed checklist is not necessary for small changes or for changes early during the project. +{% endif %} + +Where the `x` indicates that the item was completed. + +Most Git hosts have features that let you save standard replies (e.g., [GitHub's saved replies](https://help.github.com/en/articles/using-saved-replies). We suggest using these. + +If, as is occasionally appropriate, someone outside of the core development team reviews a pull request, then mention who performed the review in the pull request body and tag the pull request with the `external-review` label. + +{%- if device.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 %} + +## Integration + +{# TODO: address traceability from software items to software system tests; see 62304:5.1.1.c #} + +**Input:** Unmerged, but approved, pull-request + +Merge the approved Git branch into the `main` Git branch, correct any merge conflicts that occur. Once the branch has been merged successfully, delete the branch in {{ workflow.git_host }} [[62304:5.1.5 and 62304:5.6.1]]. + +**Output:** Merged pull request + +**Verification:** Not applicable to this activity + +## Integration and System Testing + +**Input:** Software system built using the changes from this release's change requests + +The final integration prior to a release must formally record the test output in a test record. The test record must include: + +- The list of tests that passed or failed [[62304:5.6.7.a 62304:5.7.5.a]] +- Verification that the results meet the pass/fail criteria listed in the Test Plan [[62304:5.7.4.c 62304:5.6.7.a]] +- The version of the software being tested (e.g., the Git commit hash) [[62304:5.6.7.b 62304:5.7.5.b]] +- The name of the person who ran the tests [[62304:5.6.6, 62304:5.6.7, 62304:5.7.5.c, 62304:5.6.7.c and 62304:9.8]]. + +Any test failures found during the formal release system testing shall be recorded as problem reports [[62304:5.6.8 62304:5.7.4.d]]. See the [prepare problem report activity](#prepare-problem-report) for details [[62304:5.7.2]]. If any change requests are implemented in response to these problem reports, the tests must be re-run [[62304:5.7.3.a 62304:5.7.3.b]]. If it is deemed unnecessary to re-run some of the tests, the justification as to why shall be included in the test record [[62304:5.7.3.c note that the risk management activities for (c) will be handled as part of the unit implementation and testing activity]]. + +**Output:** Test record and problem reports +[[62304:5.6.3, 62304:5.6.4, and 62304:7.3.3.d]] +**Verification:** Ensure code changes: + +- the original problem is fixed and the problem report closed [[62304:9.7.a]] +- 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]] + +## Release + +[[:This activity addresses 62304:6.3.2, since development releases and maintenance releases are treated equivalently]] + +TODO: Write out how to archive the software system release. This will vary from project to project. Here are some exmples: + +- If the output of the build process is a binary, then the binary should be saved somewhere. +- If the output is a set of Python scripts with out any SOUP, then the source code within the Git repository is already sufficient. +- If the output is a set of Python scripts with Python dependencies, then copies of the Python dependencies must be archived somewhere. Likewise, if there are other system dependencies, like postgres, then the debian package files (or perhaps a virtual box image) need to be archived. + +ENDTODO + +The purpose of the archive is to provide a means to re-test problems which may occur in an old version of the software. + +**Input:** Implemented and verified change requests for the current milestone + +When a new version of the software is released, the Git commit corresponding to the state of the code should be [tagged](https://git-scm.com/book/en/v2/Git-Basics-Tagging) with the version number. + +Archived releases shall be kept until indefinitely. + +[[:This section fulfills 62304:5.8.7.a and 62304:5.8.7.b; note that documentation and configuration items are archived automatically due to the fact that they are stored in Git]] + +**Output:** An archived software release + +**Verification:** Ensure that + +- all of the planned change requests have been implemented and integrated [[62304:5.6.2 and 62304:9.7.c]] +- the outputs of each activity are in a consistent state [[62304:5.1.6.c, 62304:5.1.6.d, and 62304:5.8.6]] +- the unit tests adequately verify the software units [[62304:5.5.2]] +- the integration tests adequately verify the software system [[62304:5.6.5 and 62304:5.7.4]] +- all software requirements have been tested or otherwise verified [[62304:5.7.4.a and 62304:5.7.4.b]] +- 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, 62304:5.8.3, and 62304:5.8.4]] + +{# When you edit the list of verification steps here, also update `init_files/documents/release_history.md` -#} + +Record these verification steps in a new software release record. + +{# TODO: add details about 14971:7 and 14971:8 #} + +## Problem Analysis + +Feedback from users, internal testers, and software developers will be recorded in {{ workflow.feedback_location }} [[62304:6.1.a, 62304:6.1.b and 62304: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 62304:6.1.b]]. + +## Prepare Problem Report + +[[:This activity addresses 62304:6.2.1.2]] + +**Input:** Feedback from users or other members of the development team + +A problem report should be created whenever: + +1. a user reports a problem while using a released version of the software system, or +2. when an internal user reports a new problem that has been found during software development or maintenance on the `main` Git branch [[62304:5.1.1.e and 62304:5.1.9.f]]. Note that small software bugs and test-failures, especially recently introduced bugs discovered by software developer working on the project, do not require a problem report. Problem reports provide a useful historical record of bugs, which can be used to identify software items which are especially risky. + +When creating a new problem report, include in the description: + +- The software item where the bug occurred (if known) +- If reported by a user, steps to recreate it +- If found in released software, the criticality of the problem +- Any relevant information that can be used to investigate the problem [[62304:9.1]]. + +**Output:** The problem report + +**Verification:** Not applicable to this activity + +## Problem Investigation + +[[:This activity addresses 62304:6.1.d and 62304:6.2.2]] + +**Input:** The problem report + +1. Investigate the problem and if possible identify the cause and record it in the problem report [[62304:9.2.a]] +2. Evaluate the problem's relevance to safety using the software [risk assessment activity](#risk-assessment) [[62304:6.2.1.3 62304:9.2.b]] +3. Consider whether the software items implicated in the investigation have the proper safety class, and address as appropriate [[62304:6.2.2 62304:7.2.2.b]] +4. Summarize the conclusions from the investigation in the problem report [[62304:9.2.c]] +5. Create a change request for actions needed to correct the problem (also include an issue reference to the problem report [[62304:8.2.4.a and 62304:8.2.4.b 62304:9.2.d]], or document the rationale for taking no action [[62304:9.2.d]]. + +**If the problem affects devices that have been released, make sure that quality control is aware of the situation and has enough information to decide whether and how to notify affected parties, including users and regulators. Record who you notified in the problem report [[62304:9.3 62304:6.2.5.a and 62304:6.2.5.b; this document does not specify the process by which quality assurance will inform users, when they must inform users, etc. It is assumed these details are handled in another process, and that all that the software developers must do is pass along the appropriate details to quality assurance.]].** + +**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 + +# Appendices + +The subsections here provide guidance on following the software risk management, development, and maintenance activities. + +## Requirements Analysis + +Writing software requirements is an art and a science; one must find balance between precision and usefulness. +{% if not device.samd %} +The distinction between system requirements and software requirements can be challenging. System requirements describe the requirements of the entire system, including software and hardware. Software requirements must be traceable to all of the system requirements that they help fulfill. Software requirements are usually more detailed than the system requirements they refer to. Many system requirements will be fulfilled using both hardware and software. +{% endif %} +The distinction between software requirements and the specifications is {% if not device.samd %}also {% endif %}typically challenging. Requirements should: + +- not imply solution +- be verifiable +- be short, ideally one or two sentences long. + +Specifications, on the other hand, should: + +- be one of possibly many solutions +- be detailed. + +Software requirements are often categorized as one of the following types [[62304:5.2.2 and 62304:5.2.3]]: + +a. Functional and capability requirements [[62304:5.2.2.a]] + - performance (e.g., purpose of software, timing requirements), + - physical characteristics (e.g., code language, platform, operating system), + - computing environment (e.g., hardware, memory size, processing unit, time zone, network infrastructure) under which the software is to perform, and + - need for compatibility with upgrades or multiple SOUP or other device versions. + +b. Software system inputs and outputs [[62304:5.2.2.b]] + - data characteristics (e.g., numerical, alpha-numeric, format) ranges, + - limits, and + - defaults. + +c. Interfaces between the software system and other systems [[62304:5.2.2.c]] + +d. Software-driven alarms, warnings, and operator messages [[62304:5.2.2.d]] + +e. Security requirements [[62304:5.2.2.e]] + - those related to the compromise of sensitive information, + - authentication, + - authorization, + - audit trail, and + - communication integrity. + +f. Usability engineering requirements that are sensitive to human errors and training [[62304:5.2.2.f]] + - support for manual operations, + - human-equipment interactions, + - constraints on personnel, and + - areas needing concentrated human attention. + +g. Data definitions and database requirements [[62304:5.2.2.g]] + +h. Installation and acceptance requirements of the delivered medical device software +at the operation and maintenance site or sites [[62304:5.2.2.h]] + +i. Requirements related to methods of operation and maintenance [[62304:5.2.2.i]] + +j. Requirements related to IT-network aspects [[62304:5.2.2.j@2015]] + +k. User maintenance requirements [[62304:5.2.2.k]] + +l. Regulatory requirements [[62304:5.2.2.l]] + +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]]. + +## Risk Management + +This subsection provides a brief introduction to risk management in the context of software development. + +**Safety** is freedom from unacceptable risk. Note that it does not mean that there is no risk, as that is impossible. The perception of risk can depend greatly on cultural, socio-economic and educational background, the actual and perceived state of health of the patient, as well as whether the hazard was avoidable. + +Our obligation as medical device software developers is to develop safe devices, while balancing economic constraints---a device that is never made can not help patients, so there may be risk associated with not bringing a device to market if the device meets a clinical problem. + +**Risk** is the combination of the probability of harm and the severity of that harm. + +**Harm** is physical injury or damage of health of people (patients or users), or damage to property or the environment. + +A **hazard** is a potential source of harm. + +A **hazardous situation** is a circumstance in which people, property, or the environment is exposed to one or more hazard(s). Not every hazardous situation leads to harm. + +Software is not itself a hazard because it can not directly cause harm, but software can contribute towards producing hazardous situations. + +{# TODO: add diagram from 14971 displaying the various components of risk #} + +{# TODO: add guidance on risk identification #} + +{# TODO: add guidance on risk estimation #} + +{# TODO: discuss probabilities of software events #} + +{# TODO: add details about the `risk.yml` file format #} + +## SOUP + +Information in the `soup.yaml` file may duplicate information found in other files (e.g., `requirements.txt` or `package.json`). + +Sometimes, especially when working on software items with low levels of concern, it can be appropriate to lump a few SOUP packages into a single item within the `soup.yml` file. + +The `soup.yaml` should contain a sequence of mappings, each containing the keys in parenthesis below. Some keys are optional. All values must be strings. + +The header of each sub-section contains the `title` of the SOUP [[62304:8.1.2.a]]. + +The `manufacturer` is the name of the company that developed the SOUP. If the manufacturer field is absent, then this SOUP was developed collaboratively by the free open-source software community, and does not have a manufacturer in the traditional sense [[62304:8.1.2.b]]. + +The `version` of each SOUP is a unique identifier, which specifies the version of the SOUP which is used in the software [[62304:8.1.2.c]]. The version may follow varying formats, such as `1.0.13`, `1.2r5`, or even `2021-05-05`, as appropriate. + +{%- if device.safety_class != "A" %} +The `purpose` of each SOUP describes the functional and performance requirements that are necessary for its intended use [[62304:5.3.3]]. + +The `requirements` will be present if there are any noteworthy hardware and software requirements for the SOUP to function properly within the system [[62304:5.3.4]]. + +The known `anomalies` present in the SOUP which may affect the functioning of {{ device.name }} should be recorded, as should the `anomaly_reference`, a location of the published anomalies list [[62304:7.1.3]]. + +When reviewing open anomalies: +- Follow a risk based approach; concentrate on high priority anomalies (assuming the SOUP manufacturer provides such a categorization). +- 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 {{ device.name }}. +{% endif -%} diff --git a/documentation/regulatory/documents/software_requirements_specification.md b/documentation/regulatory/documents/software_requirements_specification.md new file mode 100644 index 0000000..8e3f03a --- /dev/null +++ b/documentation/regulatory/documents/software_requirements_specification.md @@ -0,0 +1,146 @@ +--- +id: SRS-001 +revision: 1 +title: Software Requirements Specification +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +This document describe *what* {{ device.name }} software must do. + +This document is meant to be read and agreed-upon by the project owners and by software developers during design and construction. + +{% if not device.samd %} +The document also provides traceability between system requirements and software requirements. +{% endif %} + +[[FDA-CPSSCMD:srs]] + +# Scope + +This document applies to {{ device.name }} release {{ device.version }}. + +# Definitions + +The **Food and Drug Administration (FDA)** is a United State government agency responsible for protecting the public health by ensuring the safety, efficacy, and security of human and veterinary drugs, biological products, and medical devices. + +The **Health Insurance Portability and Accountability Act** (HIPAA) is a United States law designed to provide privacy standards to protect patients' medical records and other health information provided to health plans, doctors, hospitals and other healthcare providers. + +**Protected Health Information** (PHI) means individually identifiable information that is created by {{ device.name }} and relates to the past, present, or future physical or mental health or condition of any individual, the provision of health care to an individual, or the past, present, or future payment for the provision of health care to an individual. + +A **User** is a person who interacts with (i.e., operates or handles) the device. + +**UI** is an acronym for user interface. + +# Users + +TODO: Device Users are anyone who interacts with (i.e., operates or handles) the device. Different users will have different requirements, so it is useful to enumerate all of them so that no important requirements are missed. A few common stakeholders are listed below for convenience. + +There may be several different types of users, in which case it is worth adding more sections for each type. + +- Physical size, strength, and stamina, +- Physical dexterity, flexibility, and coordination, +- Sensory abilities (i.e., vision, hearing, tactile sensitivity), +- Cognitive abilities, including memory, +- Medical condition for which the device is being used, +- Comorbidities (i.e., multiple conditions or diseases), +- Literacy and language skills, +- General health status, +- Mental and emotional state, +- Level of education and health literacy relative to the medical condition involved, +- General knowledge of similar types of devices, +- Knowledge of and experience with the particular device, +- Ability to learn and adapt to a new device, and +- Willingness and motivation to learn to use a new device. + +ENDTODO + +This section enumerates the types of device users, describe their characteristics, and why they are interested in the device [[FDA-HFE:5.1]]. + +## Patient + +TODO: write in details, or remove this section + +## Physician + +TODO: write in details, or remove this section + +## Hospital IT Personnel + +TODO: write in details, or remove this section + +# Use Environments + +TODO: + +You should evaluate and understand relevant characteristics of all intended use environments and describe them for the purpose of HFE/UE evaluation and design. These characteristics should be taken into account during the medical device development process, so that devices might be more accommodating of the conditions of use that could affect their use safety and effectiveness. + +The environments in which medical devices are used might include a variety of conditions that could determine optimal user interface design. Medical devices might be used in clinical environments or non-clinical environments, community settings or moving vehicles. Examples of environmental use conditions include the following: + +- The lighting level might be low or high, making it hard to see device displays or controls. +- The noise level might be high, making it hard to hear device operation feedback or audible alerts and alarms or to distinguish one alarm from another. +- The room could contain multiple models of the same device, component or accessory, making it difficult to identify and select the correct one. +- The room might be full of equipment or clutter or busy with other people and activities, making it difficult for people to maneuver in the space and providing distractions that could confuse or overwhelm the device user. +- The device might be used in a moving vehicle, subjecting the device and the user to jostling and vibration that could make it difficult for the user to read a display or perform fine motor movements. + +You should evaluate and understand relevant characteristics of all intended use environments and describe them for the purpose of HFE/UE evaluation and design. These characteristics should be taken into account during the medical device development process, so that devices might be more accommodating of the conditions of use that could affect their use safety and effectiveness. + +ENDTODO + +This section enumerates the environments in which the {{ device.name }} will be used [[FDA-HFE:5.2]]. + +## Radiology Reading Room + +TODO: write in details, or remove this section + +## Radiologist's Home + +TODO: write in details, or remove this section + +# Use Cases + +## Problem X + +Brief description. + +## Problem Y + +Brief description. + +# Requirement Details +{% for requirement in requirements %} +## {{ requirement.title }} + +*Requirement ID:* {{ requirement.id }} + +{{ requirement.description }} +{% endfor %} + +# Traceability Tables +{% if device.samd %} +## Software Requirements Table + +[[ Each requirement has a unique id satisfying 62304:5.2.6.e]] +| ID | Title | +| --- | --- | +{%- for requirement in requirements %} +| {{ requirement.id }} | {{ requirement.title }} | +{%- endfor %} +{% else %} +## Software Requirements Table + +| Soft. Req. ID | System Req. IDs | Title | +| --- | --- | --- | +{%- for requirement in requirements %} +| {{ requirement.id }} | {{ requirement.system_requirements|join(', ') }} | {{ requirement.title }} | +{%- endfor %} + +## System Requirements Mapping + +| System Req. ID | Soft. Req. IDs | +| --- | --- | +{%- for system_requirement_id, software_requirement_ids in requirements|invert_dependencies('id', 'system_requirements') %} +| {{ system_requirement_id }} | {{ software_requirement_ids|sort|join(', ') }} | +{%- endfor %} +{%- endif %} diff --git a/documentation/regulatory/documents/test_record.md b/documentation/regulatory/documents/test_record.md new file mode 100644 index 0000000..be1a9de --- /dev/null +++ b/documentation/regulatory/documents/test_record.md @@ -0,0 +1,67 @@ +--- +id: TESTREC-001 +title: Software Test Record +--- +![CSC Logo](./images/CSC-logo.png) + +# Purpose + +The purpose of this document is to record the status of the software tests run for {{ device.name }}. + +# Scope + +The scope of this document is the software system within the {{ device.name }} product. + +# Verification + +I, FULL DEVELOPER NAME, verify that the results recorded here are complete and accurate [[62304:9.8.g]]. + +TODO: document the identity of the tester if any manual steps were required. + +Tests were performed on DATE TESTS COMPLETED. +TODO: document the date tested [[62304:9.8.f]] + +The tests meet our specified pass fail criteria (see Test Plan section of the Software Plan). + +# Test Environment + +TODO: Describe the test environment. This section should include all of the information necessary for someone to reproduce the tests. For example, it could be wise to include a list of all the environment variables, installed system packages and versions, the git hash, hardware used, etc. It should also include any relevant testing tools. +TODO: document the software version tested [[62304:9.8.c]] +TODO: document any relevant configuration [[62304:9.8.d]] +TODO: document the relevant tools used to run these tests [[62304:9.8.e]] + +# Test Results + +[[These are the results of automated unit and integration testing as well as manual testing 62304:9.8.a]] +TODO: List of all the tests, split into sections by type. You can use the three subsections below as a starting point. + +TODO: List any problems that were found during testing, and, if relevant, the problem report ids. +TODO: document any anomilies encountered [[62304:9.8.b]] + +It is ok if some tests do not trace to any particular requirements, however all requirements must be covered by some tests (if they are not, add tests). + +## Unit Tests + +| Test Name | Test Status | Requirement IDs | Notes | +| --- | --- | --- | --- | +{% for test_name in unit_test_record -%} +| {{ test_name }} | {{ unit_test_record[test_name].result }} | {{ unit_test_record[test_name].req_ids }} | {% if unit_test_record[test_name].note is defined %}{{ unit_test_record[test_name].note }}{% endif %} | +{% endfor %} + +## Integration Tests + +| Test Name | Test Status | Requirement IDs | Notes | +| --- | --- | --- | --- | +{% for test_name in integration_test_record -%} +| {{ test_name }} | {{ integration_test_record[test_name].result }} | {{ integration_test_record[test_name].req_ids }} | {% if integration_test_record[test_name].note is defined %}{{ integration_test_record[test_name].note }}{% endif %} | +{% endfor %} + +## Manual Tests + +| Test Name | Step | Test Status | Requirement IDs | Notes | +| --- | --- | --- | --- | --- | +{% for manual_test in manual_tests -%} +{% for manual_step in manual_test.steps -%} +| {{ manual_test.name }} | {{ manual_step.step }} | {{ manual_step.result }} | {{ manual_step.req_ids }} | {% if manual_step.note is defined %}{{ manual_step.note }}{% endif %} | +{% endfor -%} +{% endfor -%} diff --git a/documentation/regulatory/images/CSC-logo.png b/documentation/regulatory/images/CSC-logo.png new file mode 100644 index 0000000..de16bb5 Binary files /dev/null and b/documentation/regulatory/images/CSC-logo.png differ diff --git a/documentation/regulatory/images/lifecycle-processes.png b/documentation/regulatory/images/lifecycle-processes.png new file mode 100644 index 0000000..3865a9f Binary files /dev/null and b/documentation/regulatory/images/lifecycle-processes.png differ diff --git a/documentation/regulatory/images/uimockups/example-ui-mockup-001.png b/documentation/regulatory/images/uimockups/example-ui-mockup-001.png new file mode 100644 index 0000000..95d0e26 Binary files /dev/null and b/documentation/regulatory/images/uimockups/example-ui-mockup-001.png differ diff --git a/documentation/regulatory/images/uimockups/example-ui-mockup-002.jpg b/documentation/regulatory/images/uimockups/example-ui-mockup-002.jpg new file mode 100644 index 0000000..45aa42f Binary files /dev/null and b/documentation/regulatory/images/uimockups/example-ui-mockup-002.jpg differ diff --git a/documentation/regulatory/pandoc_docx.yml b/documentation/regulatory/pandoc_docx.yml new file mode 100644 index 0000000..50a09d6 --- /dev/null +++ b/documentation/regulatory/pandoc_docx.yml @@ -0,0 +1,9 @@ +from: markdown+smart +to: docx +standalone: true +table-of-contents: true +toc-depth: 2 +resource-path: +- . +metadata-file: +- ./data/device.yml diff --git a/documentation/regulatory/pandoc_pdf.yml b/documentation/regulatory/pandoc_pdf.yml new file mode 100644 index 0000000..a1ce470 --- /dev/null +++ b/documentation/regulatory/pandoc_pdf.yml @@ -0,0 +1,17 @@ +from: markdown+smart +to: latex +standalone: true +table-of-contents: true +toc-depth: 2 +pdf-engine: latexmk +extract-media: ./tmp/downloads/ +resource-path: +- . +- ./tmp/downloads/ +metadata-file: +- ./data/device.yml +variables: + linkcolor: black + urlcolor: black + geometry: "margin=1.25in" +template: "template.tex" diff --git a/documentation/regulatory/template.tex b/documentation/regulatory/template.tex new file mode 100644 index 0000000..c53f2c9 --- /dev/null +++ b/documentation/regulatory/template.tex @@ -0,0 +1,584 @@ +% This template was created using +% +% pandoc --print-default-template latex +% +% with pandoc "version 2.14.0.1". +% +% Modifications for RDM are marked with comments that begin with "RDM". +% If you're using a different version of pandoc, you may need to update this +% template and re-apply the edits, since pandoc's latex generation and this +% template are somewhat tightly coupled to each other. + +% Options for packages loaded elsewhere +\PassOptionsToPackage{unicode$for(hyperrefoptions)$,$hyperrefoptions$$endfor$}{hyperref} +\PassOptionsToPackage{hyphens}{url} +$if(colorlinks)$ +\PassOptionsToPackage{dvipsnames,svgnames,x11names}{xcolor} +$endif$ +$if(dir)$ +$if(latex-dir-rtl)$ +\PassOptionsToPackage{RTLdocument}{bidi} +$endif$ +$endif$ +$if(CJKmainfont)$ +\PassOptionsToPackage{space}{xeCJK} +$endif$ +% +\documentclass[ +$if(fontsize)$ + $fontsize$, +$endif$ +$if(lang)$ + $babel-lang$, +$endif$ +$if(papersize)$ + $papersize$paper, +$endif$ +$if(beamer)$ + ignorenonframetext, +$if(handout)$ + handout, +$endif$ +$if(aspectratio)$ + aspectratio=$aspectratio$, +$endif$ +$endif$ +$for(classoption)$ + $classoption$$sep$, +$endfor$ +]{$documentclass$} +$if(title)$ +% RDM begin +%\title{$title$$if(thanks)$\thanks{$thanks$}$endif$} +\title{$title$$if(id)$\\ \large $id$$if(revision)$, Rev. $revision$$endif$$endif$} +% RDM end +$endif$ +$if(subtitle)$ +$if(beamer)$ +$else$ +\usepackage{etoolbox} +\makeatletter +\providecommand{\subtitle}[1]{% add subtitle to \maketitle + \apptocmd{\@title}{\par {\large #1 \par}}{}{} +} +\makeatother +$endif$ +\subtitle{$subtitle$} +$endif$ + +% RDM begin +$if(manufacturer)$ +\author{$manufacturer$} +$endif$ +%\author{$for(author)$$author$$sep$ \and $endfor$} +% RDM end +\date{$date$} +$if(beamer)$ +$if(institute)$ +\institute{$for(institute)$$institute$$sep$ \and $endfor$} +$endif$ +$if(titlegraphic)$ +\titlegraphic{\includegraphics{$titlegraphic$}} +$endif$ +$if(logo)$ +\logo{\includegraphics{$logo$}} +$endif$ +$endif$ + +% RDM begin +\usepackage{fancyhdr} +\usepackage{lastpage} +\pagestyle{fancy} +$if(title)$ +\lhead{$title$} +$endif$ +$if(id)$ +\rhead{$id$$if(revision)$, Rev. $revision$$endif$} +$endif$ +% NOTE: the LastPage ref triggers a warning on the first +% latexmk pass ("Latex failed to resolve 1 reference(s)") +\cfoot{Page \thepage\ of \pageref{LastPage}} +% RDM end + +$if(beamer)$ +$if(background-image)$ +\usebackgroundtemplate{% + \includegraphics[width=\paperwidth]{$background-image$}% +} +$endif$ +\usepackage{pgfpages} +\setbeamertemplate{caption}[numbered] +\setbeamertemplate{caption label separator}{: } +\setbeamercolor{caption name}{fg=normal text.fg} +\beamertemplatenavigationsymbols$if(navigation)$$navigation$$else$empty$endif$ +$for(beameroption)$ +\setbeameroption{$beameroption$} +$endfor$ +% Prevent slide breaks in the middle of a paragraph +\widowpenalties 1 10000 +\raggedbottom +$if(section-titles)$ +\setbeamertemplate{part page}{ + \centering + \begin{beamercolorbox}[sep=16pt,center]{part title} + \usebeamerfont{part title}\insertpart\par + \end{beamercolorbox} +} +\setbeamertemplate{section page}{ + \centering + \begin{beamercolorbox}[sep=12pt,center]{part title} + \usebeamerfont{section title}\insertsection\par + \end{beamercolorbox} +} +\setbeamertemplate{subsection page}{ + \centering + \begin{beamercolorbox}[sep=8pt,center]{part title} + \usebeamerfont{subsection title}\insertsubsection\par + \end{beamercolorbox} +} +\AtBeginPart{ + \frame{\partpage} +} +\AtBeginSection{ + \ifbibliography + \else + \frame{\sectionpage} + \fi +} +\AtBeginSubsection{ + \frame{\subsectionpage} +} +$endif$ +$endif$ +$if(beamerarticle)$ +\usepackage{beamerarticle} % needs to be loaded first +$endif$ +\usepackage{amsmath,amssymb} +$if(fontfamily)$ +\usepackage[$for(fontfamilyoptions)$$fontfamilyoptions$$sep$,$endfor$]{$fontfamily$} +$else$ +\usepackage{lmodern} +$endif$ +$if(linestretch)$ +\usepackage{setspace} +$endif$ +\usepackage{iftex} +\ifPDFTeX + \usepackage[$if(fontenc)$$fontenc$$else$T1$endif$]{fontenc} + \usepackage[utf8]{inputenc} + \usepackage{textcomp} % provide euro and other symbols +\else % if luatex or xetex +$if(mathspec)$ + \ifXeTeX + \usepackage{mathspec} + \else + \usepackage{unicode-math} + \fi +$else$ + \usepackage{unicode-math} +$endif$ + \defaultfontfeatures{Scale=MatchLowercase} + \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1} +$if(mainfont)$ + \setmainfont[$for(mainfontoptions)$$mainfontoptions$$sep$,$endfor$]{$mainfont$} +$endif$ +$if(sansfont)$ + \setsansfont[$for(sansfontoptions)$$sansfontoptions$$sep$,$endfor$]{$sansfont$} +$endif$ +$if(monofont)$ + \setmonofont[$for(monofontoptions)$$monofontoptions$$sep$,$endfor$]{$monofont$} +$endif$ +$for(fontfamilies)$ + \newfontfamily{$fontfamilies.name$}[$for(fontfamilies.options)$$fontfamilies.options$$sep$,$endfor$]{$fontfamilies.font$} +$endfor$ +$if(mathfont)$ +$if(mathspec)$ + \ifXeTeX + \setmathfont(Digits,Latin,Greek)[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} + \else + \setmathfont[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} + \fi +$else$ + \setmathfont[$for(mathfontoptions)$$mathfontoptions$$sep$,$endfor$]{$mathfont$} +$endif$ +$endif$ +$if(CJKmainfont)$ + \ifXeTeX + \usepackage{xeCJK} + \setCJKmainfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} + \fi +$endif$ +$if(luatexjapresetoptions)$ + \ifLuaTeX + \usepackage[$for(luatexjapresetoptions)$$luatexjapresetoptions$$sep$,$endfor$]{luatexja-preset} + \fi +$endif$ +$if(CJKmainfont)$ + \ifLuaTeX + \usepackage[$for(luatexjafontspecoptions)$$luatexjafontspecoptions$$sep$,$endfor$]{luatexja-fontspec} + \setmainjfont[$for(CJKoptions)$$CJKoptions$$sep$,$endfor$]{$CJKmainfont$} + \fi +$endif$ +\fi +$if(zero-width-non-joiner)$ +%% Support for zero-width non-joiner characters. +\makeatletter +\def\zerowidthnonjoiner{% + % Prevent ligatures and adjust kerning, but still support hyphenating. + \texorpdfstring{% + \textormath{\nobreak\discretionary{-}{}{\kern.03em}% + \ifvmode\else\nobreak\hskip\z@skip\fi}{}% + }{}% +} +\makeatother +\ifPDFTeX + \DeclareUnicodeCharacter{200C}{\zerowidthnonjoiner} +\else + \catcode`^^^^200c=\active + \protected\def ^^^^200c{\zerowidthnonjoiner} +\fi +%% End of ZWNJ support +$endif$ +$if(beamer)$ +$if(theme)$ +\usetheme[$for(themeoptions)$$themeoptions$$sep$,$endfor$]{$theme$} +$endif$ +$if(colortheme)$ +\usecolortheme{$colortheme$} +$endif$ +$if(fonttheme)$ +\usefonttheme{$fonttheme$} +$endif$ +$if(mainfont)$ +\usefonttheme{serif} % use mainfont rather than sansfont for slide text +$endif$ +$if(innertheme)$ +\useinnertheme{$innertheme$} +$endif$ +$if(outertheme)$ +\useoutertheme{$outertheme$} +$endif$ +$endif$ +% Use upquote if available, for straight quotes in verbatim environments +\IfFileExists{upquote.sty}{\usepackage{upquote}}{} +\IfFileExists{microtype.sty}{% use microtype if available + \usepackage[$for(microtypeoptions)$$microtypeoptions$$sep$,$endfor$]{microtype} + \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts +}{} +$if(indent)$ +$else$ +\makeatletter +\@ifundefined{KOMAClassName}{% if non-KOMA class + \IfFileExists{parskip.sty}{% + \usepackage{parskip} + }{% else + \setlength{\parindent}{0pt} + \setlength{\parskip}{6pt plus 2pt minus 1pt}} +}{% if KOMA class + \KOMAoptions{parskip=half}} +\makeatother +$endif$ +$if(verbatim-in-note)$ +\usepackage{fancyvrb} +$endif$ +\usepackage{xcolor} +\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available +\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}} +\hypersetup{ +$if(title-meta)$ + pdftitle={$title-meta$}, +$endif$ +$if(author-meta)$ + pdfauthor={$author-meta$}, +$endif$ +$if(lang)$ + pdflang={$lang$}, +$endif$ +$if(subject)$ + pdfsubject={$subject$}, +$endif$ +$if(keywords)$ + pdfkeywords={$for(keywords)$$keywords$$sep$, $endfor$}, +$endif$ +$if(colorlinks)$ + colorlinks=true, + linkcolor={$if(linkcolor)$$linkcolor$$else$Maroon$endif$}, + filecolor={$if(filecolor)$$filecolor$$else$Maroon$endif$}, + citecolor={$if(citecolor)$$citecolor$$else$Blue$endif$}, + urlcolor={$if(urlcolor)$$urlcolor$$else$Blue$endif$}, +$else$ + hidelinks, +$endif$ + pdfcreator={LaTeX via pandoc}} +\urlstyle{same} % disable monospaced font for URLs +$if(verbatim-in-note)$ +\VerbatimFootnotes % allow verbatim text in footnotes +$endif$ +$if(geometry)$ +$if(beamer)$ +\geometry{$for(geometry)$$geometry$$sep$,$endfor$} +$else$ +\usepackage[$for(geometry)$$geometry$$sep$,$endfor$]{geometry} +$endif$ +$endif$ +$if(beamer)$ +\newif\ifbibliography +$endif$ +$if(listings)$ +\usepackage{listings} +\newcommand{\passthrough}[1]{#1} +\lstset{defaultdialect=[5.3]Lua} +\lstset{defaultdialect=[x86masm]Assembler} +$endif$ +$if(lhs)$ +\lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{} +$endif$ +$if(highlighting-macros)$ +$highlighting-macros$ +$endif$ +$if(tables)$ +\usepackage{longtable,booktabs,array} +$if(multirow)$ +\usepackage{multirow} +$endif$ +\usepackage{calc} % for calculating minipage widths +$if(beamer)$ +\usepackage{caption} +% Make caption package work with longtable +\makeatletter +\def\fnum@table{\tablename~\thetable} +\makeatother +$else$ +% Correct order of tables after \paragraph or \subparagraph +\usepackage{etoolbox} +\makeatletter +\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{} +\makeatother +% Allow footnotes in longtable head/foot +\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}} +\makesavenoteenv{longtable} +$endif$ +$endif$ +$if(graphics)$ +\usepackage{graphicx} +\makeatletter +\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi} +\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi} +\makeatother +% Scale images if necessary, so that they will not overflow the page +% margins by default, and it is still possible to overwrite the defaults +% using explicit options in \includegraphics[width, height, ...]{} +\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} +% Set default figure placement to htbp +\makeatletter +\def\fps@figure{htbp} +\makeatother +$endif$ +$if(links-as-notes)$ +% Make links footnotes instead of hotlinks: +\DeclareRobustCommand{\href}[2]{#2\footnote{\url{#1}}} +$endif$ +$if(strikeout)$ +\usepackage[normalem]{ulem} +% Avoid problems with \sout in headers with hyperref +\pdfstringdefDisableCommands{\renewcommand{\sout}{}} +$endif$ +\setlength{\emergencystretch}{3em} % prevent overfull lines +\providecommand{\tightlist}{% + \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}} +$if(numbersections)$ +\setcounter{secnumdepth}{$if(secnumdepth)$$secnumdepth$$else$5$endif$} +$else$ +\setcounter{secnumdepth}{-\maxdimen} % remove section numbering +$endif$ +$if(beamer)$ +$else$ +$if(block-headings)$ +% Make \paragraph and \subparagraph free-standing +\ifx\paragraph\undefined\else + \let\oldparagraph\paragraph + \renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}} +\fi +\ifx\subparagraph\undefined\else + \let\oldsubparagraph\subparagraph + \renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}} +\fi +$endif$ +$endif$ +$if(pagestyle)$ +\pagestyle{$pagestyle$} +$endif$ +$if(csl-refs)$ +\newlength{\cslhangindent} +\setlength{\cslhangindent}{1.5em} +\newlength{\csllabelwidth} +\setlength{\csllabelwidth}{3em} +\newlength{\cslentryspacingunit} % times entry-spacing +\setlength{\cslentryspacingunit}{\parskip} +\newenvironment{CSLReferences}[2] % #1 hanging-ident, #2 entry spacing + {% don't indent paragraphs + \setlength{\parindent}{0pt} + % turn on hanging indent if param 1 is 1 + \ifodd #1 + \let\oldpar\par + \def\par{\hangindent=\cslhangindent\oldpar} + \fi + % set entry spacing + \setlength{\parskip}{#2\cslentryspacingunit} + }% + {} +\usepackage{calc} +\newcommand{\CSLBlock}[1]{#1\hfill\break} +\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{#1}} +\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{#1}\break} +\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1} +$endif$ +$for(header-includes)$ +$header-includes$ +$endfor$ +$if(lang)$ +\ifXeTeX + % Load polyglossia as late as possible: uses bidi with RTL langages (e.g. Hebrew, Arabic) + \usepackage{polyglossia} + \setmainlanguage[$for(polyglossia-lang.options)$$polyglossia-lang.options$$sep$,$endfor$]{$polyglossia-lang.name$} +$for(polyglossia-otherlangs)$ + \setotherlanguage[$for(polyglossia-otherlangs.options)$$polyglossia-otherlangs.options$$sep$,$endfor$]{$polyglossia-otherlangs.name$} +$endfor$ +\else + \usepackage[$for(babel-otherlangs)$$babel-otherlangs$,$endfor$main=$babel-lang$]{babel} +% get rid of language-specific shorthands (see #6817): +\let\LanguageShortHands\languageshorthands +\def\languageshorthands#1{} +$if(babel-newcommands)$ + $babel-newcommands$ +$endif$ +\fi +$endif$ +\ifLuaTeX + \usepackage{selnolig} % disable illegal ligatures +\fi +$if(dir)$ +\ifXeTeX + % Load bidi as late as possible as it modifies e.g. graphicx + \usepackage{bidi} +\fi +\ifPDFTeX + \TeXXeTstate=1 + \newcommand{\RL}[1]{\beginR #1\endR} + \newcommand{\LR}[1]{\beginL #1\endL} + \newenvironment{RTL}{\beginR}{\endR} + \newenvironment{LTR}{\beginL}{\endL} +\fi +$endif$ +$if(natbib)$ +\usepackage[$natbiboptions$]{natbib} +\bibliographystyle{$if(biblio-style)$$biblio-style$$else$plainnat$endif$} +$endif$ +$if(biblatex)$ +\usepackage[$if(biblio-style)$style=$biblio-style$,$endif$$for(biblatexoptions)$$biblatexoptions$$sep$,$endfor$]{biblatex} +$for(bibliography)$ +\addbibresource{$bibliography$} +$endfor$ +$endif$ +$if(nocite-ids)$ +\nocite{$for(nocite-ids)$$it$$sep$, $endfor$} +$endif$ +$if(csquotes)$ +\usepackage{csquotes} +$endif$ + +\begin{document} +$if(has-frontmatter)$ +\frontmatter +$endif$ +$if(title)$ +$if(beamer)$ +\frame{\titlepage} +$else$ +\maketitle +$endif$ +$if(abstract)$ +\begin{abstract} +$abstract$ +\end{abstract} +$endif$ +$endif$ + +$for(include-before)$ +$include-before$ + +$endfor$ +$if(toc)$ +$if(toc-title)$ +\renewcommand*\contentsname{$toc-title$} +$endif$ +$if(beamer)$ +\begin{frame}[allowframebreaks] +$if(toc-title)$ + \frametitle{$toc-title$} +$endif$ + \tableofcontents[hideallsubsections] +\end{frame} +$else$ +{ +$if(colorlinks)$ +\hypersetup{linkcolor=$if(toccolor)$$toccolor$$else$$endif$} +$endif$ +\setcounter{tocdepth}{$toc-depth$} +\tableofcontents +} +$endif$ +$endif$ +$if(lof)$ +\listoffigures +$endif$ +$if(lot)$ +\listoftables +$endif$ +$if(linestretch)$ +\setstretch{$linestretch$} +$endif$ +$if(has-frontmatter)$ +\mainmatter +$endif$ +$body$ + +$if(has-frontmatter)$ +\backmatter +$endif$ +$if(natbib)$ +$if(bibliography)$ +$if(biblio-title)$ +$if(has-chapters)$ +\renewcommand\bibname{$biblio-title$} +$else$ +\renewcommand\refname{$biblio-title$} +$endif$ +$endif$ +$if(beamer)$ +\begin{frame}[allowframebreaks]{$biblio-title$} + \bibliographytrue +$endif$ + \bibliography{$for(bibliography)$$bibliography$$sep$,$endfor$} +$if(beamer)$ +\end{frame} +$endif$ + +$endif$ +$endif$ +$if(biblatex)$ +$if(beamer)$ +\begin{frame}[allowframebreaks]{$biblio-title$} + \bibliographytrue + \printbibliography[heading=none] +\end{frame} +$else$ +\printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$ +$endif$ + +$endif$ +$for(include-after)$ +$include-after$ + +$endfor$ +\end{document} diff --git a/requirements.txt b/requirements.txt index dab5c04..973b2ce 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,3 @@ pytorch_lightning==1.3.0 -mlflow \ No newline at end of file +mlflow~=1.19 +rdm~=0.11 \ No newline at end of file