From fa1a7e3845030862febe012c9649c290bc12ad59 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Thu, 12 Oct 2023 10:22:59 +0100 Subject: [PATCH 01/14] Add mock documentation --- README.md | 301 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 280 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 335c22d..edc74bc 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,288 @@ -# prototype-ci-reading +# Proposed Quality Workflow (QW) user guide - release 1 -Quick prototype for processing PR and issue data in github actions +The Quality Workflow tool (QW) aims to help reduce the friction in creating and maintaining traceability matrices (later release could target hazards and risks). -## Ensuring that we can access these parts in CI +# Background and use-case -Issues +Within medical device software there are several design and development stages that should be tracked, versioned and a traceability matrix is a standard way of presenting this information. The Quality Management System used in WEISS is document based, which requires substantial manual effort in tracking linkages, updating of versions and ensuring that all approvals are current. -- [x] Title -- [x] First comment -- [x] PR number -- [x] Assignee(s) - - If we're using names, they're not required on github so could end up being blank - - We could just use github logins and have part of the config that you have to map gh logins - to names as you want them on the report information -- [x] Label +The QW allows users to track the different changes in design and development requirements, outputs, verification and validations. These different stages are linked together using github or gitlab as part of the normal development process. QW also will ensure that versioning of items are updated if their contents have changed, and notify when manual verification should be rerun due to changes in requirements or outputs. -PRs +# Setup -- [x] Title -- [x] First comment -- [x] Assignee(s) -- [x] Users who's final reviews were APPROVED -- [x] Label -- [x] [Linked Issues](https://github.com/cli/cli/discussions/7097#discussioncomment-5229031) +## Installation -## Prototyping of QW tool +The `qw` tool requires python 3.9 or greater, if your project is in python then we suggest adding it to the developer requirements. Otherwise may want to create a virtual environment for your python, one option is the [venv](https://docs.python.org/3.9/library/venv.html) module. -Messing around with python in [src](src) +For Unix: + +```shell +python -m venv env --prompt qw # create virtual environment directory called `venv` +source venv/bin/activate # use the virtual environment +pip install git+https://github.com/UCL-ARC/qw.git#egg=qw # install qw +echo "venv" >> .gitignore. # ensure git ignores the `venv` directory +``` + +## Configuration using Github + +### Initial setup and adding to repository + +The `qw` tool creates a `.qw` directory that allows versions of each design and development stage to be tracked at release time. We suggest adding this directory to your version control, so that there is a shared baseline at each release. In the first step it also creates a set of github actions and templates to ensure the tool can work correctly. To allow the `qw` to interact with github you will need to create a fine-grained personal access token. The final step of configuration then updates your github repository with rules , and add templates for each stage of the quality workflow (and another template if there is an issue or pull request that doesn't relate to the quality management documentation). + +#### Initialise `qw` + +At the top level of your git repository, run the intialisation step for github + +```shell +qw init --repo github.com:username/reponame --service github +``` + +> INFO: A ".qw" directory has been created +> INFO: Github actions for qw have been added to your ".github" directory +> INFO: Templates added to your ".github" directory: "User need", "Design input", "Design output", "Pull request" +> INFO: Please commit the files after you have finished your setup +> INFO: Rulesets and branch protection added for branches matching "main" to "stefpiatek/dummy-medical-software" + +If you have a different development flow than using the default branch, then edit the `qw` ruleset for the repository, adding extra branches to the ruleset (e.g. `develop`) + + + +You can omit `--service github` if the repo is at `github.com` (as in +this case) and you can omit `--repo ` if you have the desired +repository configured as the git remote named `upstream`. + +#### Setup Personal Access Token + +- Follow the [github instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) we suggest the following configuration options: + + | field | value, user defined values defined by `${...}` | + | ----------------- | ----------------------------------------------------------- | + | Token name | `qw-${repository_name}` | + | Expiration | `custom...` then choose 364 days from today | + | Description | `QW tool for ${repository_name}` | + | Repository access | `Only select repositories` -> Select the project repository | + | Permissions | Only add repository permissions, see next table | + + | repository permissions | value | + | ---------------------- | -------------- | + | Actions | Read and write | + | Contents | Read-only | + | Issues | Read and write | + | Metadata | Read-only | + | Pull Requests | Read and write | + + Then click the `Generate token` button and copy the token (you can't get its value again if you close the page). + +- Add the personal access token to your machine's keychain (uses [keyring](https://pypi.org/project/keyring/)) + + ```shell + qw login + ``` + + + + > Please copy the personal access token and hit enter: + + After you've done this, the system will check the personal access token. If you've configured for the remote URL you would see: + + > INFO: Can access "stefpiatek/dummy-medical-software" + +### Setup for a new user, on an existing project that uses QW + +The local and github repository have already been configured to work with `qw`, you'll just need to [add the personal access token](#setup-personal-access-token) + +### Customising configuration + +QW initialises with a `System` component for design inputs (used for generating a unique identifier, short code value is `X`). +You can add extra components to the configuration using qw: + +```shell +qw config add-service --name="Drug dosage" --short-code=D +``` + +> INFO: Added "Drug dosage (D)" to local compenents, please commit this file +> INFO: Added tag "qw-component-d" to github + +## Configuration using Gitlab + +Intentionally left blank at the moment for brevity. Will aim for being able to implement this. + +# Using QW with github + +QW uses existing issues and pull requests to track the different design and development stages along with managing risks and their mitigations. + +## Creating QW items + +### User needs + +- In your github repository, Add a new issue, selecting the User needs template + ![](https://hackmd.io/_uploads/Syo1w1oy6.png) +- Fill out the required fields and any other information if it exists + ![](https://hackmd.io/_uploads/rJG7_1okT.png) +- Hit `Submit new issue` and the issue will be rendered like this: ![](https://hackmd.io/_uploads/BktGcJo1p.png) +- The first comment of this issue will be used by `qw` for tracking, but you can edit anything manually after the `Other information` header and this will not interfere with the tool + +### Design inputs + +- In your github repository, Add a new issue, selecting the User needs template + ![](https://hackmd.io/_uploads/Syo1w1oy6.png) +- Fill out the required fields and any other information that may be useful + ![](https://hackmd.io/_uploads/B1X07JVZ6.png) + - The options for requirements type are: + - Functional + - System inputs and outputs + - Application programming interface + - Alarms and warnings + - Security + - User interface + - Data definition and database + - Installation and acceptance + - Operation methods and maintenance + - Networking + - User maintenance + - Regulatory +- Hit `Submit new issue` and theissue will be rendered like this: + ![](https://hackmd.io/_uploads/B1m9SkVZ6.png) + + - Note that the `design-component-d` has been added as "Drug dosage" was added as a component type with a short code of `D`. + +- The first comment of this issue will be used by `qw` for tracking, but you can edit anything manually after the `Other information` header and this will not interfere with the tool +- The parent issue will have been updated with this issue number + ![](https://hackmd.io/_uploads/HJODNgiya.png) + +### Design outputs and design verification + +- Create a pull request from github and follow the instructions on the template + ![](https://hackmd.io/_uploads/BkYpd7ikp.png) + - If the `qw-ignore` tag is added, then this PR does is not related to the medical device aspect of the software +- In this example, the pull request contains the design outputs and design verification. These can be added seperately, where the design verification would also be linked to the design input. + ![](https://hackmd.io/_uploads/ryp39Xj1a.png) +- QW will check that the chain of design items are able to be processed and fully signed off, + when this is successful the github action will pass + ![](https://hackmd.io/_uploads/H1Ix67i16.png) +- QW requires a pull request that is labelled as a `design-validation` or `design-verification` to have at least one automated test that targets a specific `design-output`, `design-input` or `user-need` + - Tests are tracked manually in `.qw/test_mapping.csv` where multiple issues are separated by `;`, in the following structure + test name | issue(s) targetted + -- | -- + InputVerifierTests::testWeightIsNegative | 40 + InputVerifierTests::testConversionOfWeightUnits | 4;23 + acceptance_test_user_entry.docx | 2 + - The development team may want to write a script that allows them to get the names of all tests run and ensure that automated tests listed in the csv still exist, bonus points if you make this an automated test that fails if a test doesn't exist + - Adding the manual verification test scripts to version control is ideal, but you may also list the name + - the QW CI task will can fail if: + - No parent issue is given for a PR + - A test doesn't exist which is mapped to the parent issue + - The structure of the `test_mapping.csv` has been altered, or `;` has not been used to separate targetted issues + - A test name is duplicated in `test_mapping.csv` + +### Design validation + +- QW does not require design validation documentation to be added to the repository, + but you may add the test script. + Ideally this would be in a plain text format. We suggest creating a + `validation` directory and storing the validation information there +- As with [Design outputs and design verification](#design-outputs-and-design-verification), update the `.qw/test_mapping.csv` with the test script(s) that fulfill the user need. +- Create a pull request from github and follow the instructions on the template + ![](https://hackmd.io/_uploads/BkYpd7ikp.png) + - A validation links to a user need, so link this type of issue in the PR + - Assign the pull request to the team member who will authorise the validation. + Once they have validated it and signed any required paperwork, + they should approve the PR. + +### Non-QW items + +- If you'd like to create an issue that doesn't relate to the medical device then use the `Non QW item` issue template. + This tags the issue with `qw-ignore` so that QW does not parse the issue. + ![](https://hackmd.io/_uploads/SkWcEzQgp.png) +- If you'd like to create a pull request that doesn't relate to the medical device then tag the pull request with `qw-ignore`. + +## Closing QW items when they are not resolved by a PR + +- There may be times where an QW-tracked issue is required to be closed not by a PR. +- You may close the issue as either `completed` or `not planned` ![](https://hackmd.io/_uploads/Sy22Bi9x6.png) +- Then please add the `qw` tag that matches the reason. The options for tags are:`qw-close-duplicate`, `qw-close-wont-fix`, `qw-close-duplicate`, , `qw-close-cannot-replicate`, `qw-close-not-a-defect` +- [name=Stef] Alternatively we could have a manual closure reason in the issue template, and then that is required to be filled with free text as a reason? + +## Versioning of QW items + +The `qw freeze` function is used to save the current state of the qw items in github, and to ensure that the versions of items are updated if their information has changed. +This should be run regularly, which will update or add to the `.qw` directory. +These changes should be committed and added to the main development branch by a pull request as a [Non QW item](#non-qw-items). + +``` +qw freeze +``` + +An example incrementing a tag upon update: + +> Running WQ freeze +> Found 47 QW items +> +> INFO: Design Input https://github.com/stefpiatek/dummy-medical-software/issues/6 has a been updated since last saved +> +> Previous data: +> +> - Description : Warfarin dosage should be calculated using based on patient age, gender and weight +> - Parent User need: https://github.com/stefpiatek/dummy-medical-software/issues/5 +> +> Current Data: +> +> - Description : Warfarin dosage in mg/kg should be calculated using based on patient age, gender and weight +> - Parent User need: https://github.com/stefpiatek/dummy-medical-software/issues/5 +> +> Would you like to increment the version? (y/n): +> INFO: Updated tag to "qw-v2" +> INFO: There are 2 design outputs that link to this Design Input, please ensure one of them has the "qw-v2" tag if it resolves the updated information +> +> - https://github.com/stefpiatek/dummy-medical-software/pull/7 +> - https://github.com/stefpiatek/dummy-medical-software/pull/12 +> ... +> INFO: :heavy_check_mark: 12 new QW items added to state +> INFO: :heavy_check_mark: 47 QW items checked +> INFO: Please commit the changes in the ".qw" directory + +Example response when the change is trivial and does not warrant a change in the version of the QW item: + +> ... +> Would you like to increment the version? (y/n): +> INFO: Tag kept at "qw-v1", data for the Design Input has been updated to the current state +> ... + +### Creating a documentation release + +When you're ready to update the documentation in your Quality Management System (QMS), you can use the QW tool's `release` command. +Running this will: + +- Ensure that all issues and pull requests have been marked with `qw-ignore` or one of the `qw-` item tags, raising an error (and stopping) to ensure all items are tagged +- Ensure that all QW items have versions +- Ensure the entire chain `design validation -> design verification -> design output -> design input -> user need` is consistent with QW rules, starting from the furthest stage of QW items. So if there is no `design validation`, then the chain will start from `design verification`. If there was only a `user need` and `design input`s, then only these would be validated +- Create word documents based on the QW template for export +- [name=Stef] Optionally? Create an html page that shows a burndown graph for each of the QW item types, showing the number completed and outstanding over time. Would this be useful? + +``` +qw release qms_docs +``` + +> Creating a release for QW +> Creating "qms_docs" directory if it doesn't already exist, and overwriting any previously exported files +> INFO: :heavy_check_mark: 47 QW items checked +> INFO: :heavy_check_mark: Documents have been written to the "qms_docs" directory + +# FAQ and common issues + +- Can I import an existing project into QW + - There's nothing stopping this, though each issue and pull request would need to match the required format, and be tagged appropriately by the time you'd like to run a release. This may be a reasonable amount of work and we expect issues may need to be created. +- + +# Open questions + +- Which document parts are the most useful for export, and would we want the user to be able to edit the template (update styles and placeholder text?) +- Would the burndown chart be useful to get an overview for development? +- Gate who can authorise a PR, or can anyone? +- Should we include a change request at this stage, or keep it with the risk management side of things +- closed not by a PR - would be useful to get a steer on what is required or most useful From 3420beec8838fe2b94a210d28462a8a049de7209 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Thu, 12 Oct 2023 10:32:44 +0100 Subject: [PATCH 02/14] Use shell code blocks in documentation --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index edc74bc..d12ab4d 100644 --- a/README.md +++ b/README.md @@ -214,7 +214,7 @@ The `qw freeze` function is used to save the current state of the qw items in gi This should be run regularly, which will update or add to the `.qw` directory. These changes should be committed and added to the main development branch by a pull request as a [Non QW item](#non-qw-items). -``` +```shell qw freeze ``` @@ -264,7 +264,7 @@ Running this will: - Create word documents based on the QW template for export - [name=Stef] Optionally? Create an html page that shows a burndown graph for each of the QW item types, showing the number completed and outstanding over time. Would this be useful? -``` +```shell qw release qms_docs ``` From 0922e80fd7f210e6096cf35fd53afacb14ac15d8 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Thu, 12 Oct 2023 10:33:04 +0100 Subject: [PATCH 03/14] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d12ab4d..50fc4ac 100644 --- a/README.md +++ b/README.md @@ -223,7 +223,7 @@ An example incrementing a tag upon update: > Running WQ freeze > Found 47 QW items > -> INFO: Design Input https://github.com/stefpiatek/dummy-medical-software/issues/6 has a been updated since last saved +> INFO: Design Input https://github.com/stefpiatek/dummy-medical-software/issues/6 has been updated since last saved > > Previous data: > From 660cea0e7bc16c9b7cf18a62fdfbcd4a2c4f66d4 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Thu, 12 Oct 2023 13:50:28 +0100 Subject: [PATCH 04/14] Update images to use tasklists --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 50fc4ac..e7c0ff2 100644 --- a/README.md +++ b/README.md @@ -147,13 +147,11 @@ QW uses existing issues and pull requests to track the different design and deve - User maintenance - Regulatory - Hit `Submit new issue` and theissue will be rendered like this: - ![](https://hackmd.io/_uploads/B1m9SkVZ6.png) - + ![](https://hackmd.io/_uploads/H1-xiDBWT.png) - Note that the `design-component-d` has been added as "Drug dosage" was added as a component type with a short code of `D`. - - The first comment of this issue will be used by `qw` for tracking, but you can edit anything manually after the `Other information` header and this will not interfere with the tool - The parent issue will have been updated with this issue number - ![](https://hackmd.io/_uploads/HJODNgiya.png) + ![](https://hackmd.io/_uploads/S1OvqDrW6.png) ### Design outputs and design verification From 65fe274031a4be5d4cd79959f6029c39dc6dec87 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Thu, 12 Oct 2023 14:04:19 +0100 Subject: [PATCH 05/14] fix typo Co-authored-by: Haroon Chughtai --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e7c0ff2..acc5401 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ You can add extra components to the configuration using qw: qw config add-service --name="Drug dosage" --short-code=D ``` -> INFO: Added "Drug dosage (D)" to local compenents, please commit this file +> INFO: Added "Drug dosage (D)" to local components, please commit this file > INFO: Added tag "qw-component-d" to github ## Configuration using Gitlab From f8443c25e5feffeb5668849d554baf10bfcac31b Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Thu, 12 Oct 2023 14:12:47 +0100 Subject: [PATCH 06/14] Yet another typo Co-authored-by: Haroon Chughtai --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index acc5401..7296129 100644 --- a/README.md +++ b/README.md @@ -175,7 +175,7 @@ QW uses existing issues and pull requests to track the different design and deve - the QW CI task will can fail if: - No parent issue is given for a PR - A test doesn't exist which is mapped to the parent issue - - The structure of the `test_mapping.csv` has been altered, or `;` has not been used to separate targetted issues + - The structure of the `test_mapping.csv` has been altered, or `;` has not been used to separate targeted issues - A test name is duplicated in `test_mapping.csv` ### Design validation From 605ab447161c4b927c7ff7f3bdc2496828e1abae Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Thu, 12 Oct 2023 14:15:35 +0100 Subject: [PATCH 07/14] Remove unused word --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7296129..395420d 100644 --- a/README.md +++ b/README.md @@ -172,7 +172,7 @@ QW uses existing issues and pull requests to track the different design and deve acceptance_test_user_entry.docx | 2 - The development team may want to write a script that allows them to get the names of all tests run and ensure that automated tests listed in the csv still exist, bonus points if you make this an automated test that fails if a test doesn't exist - Adding the manual verification test scripts to version control is ideal, but you may also list the name - - the QW CI task will can fail if: + - the QW CI task will fail if: - No parent issue is given for a PR - A test doesn't exist which is mapped to the parent issue - The structure of the `test_mapping.csv` has been altered, or `;` has not been used to separate targeted issues From e9d910053fba824e623b5f355b98a126ad5059d1 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Fri, 13 Oct 2023 17:11:41 +0100 Subject: [PATCH 08/14] fix typo Co-authored-by: Haroon Chughtai --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 395420d..6808328 100644 --- a/README.md +++ b/README.md @@ -158,7 +158,7 @@ QW uses existing issues and pull requests to track the different design and deve - Create a pull request from github and follow the instructions on the template ![](https://hackmd.io/_uploads/BkYpd7ikp.png) - If the `qw-ignore` tag is added, then this PR does is not related to the medical device aspect of the software -- In this example, the pull request contains the design outputs and design verification. These can be added seperately, where the design verification would also be linked to the design input. +- In this example, the pull request contains the design outputs and design verification. These can be added separately, where the design verification would also be linked to the design input. ![](https://hackmd.io/_uploads/ryp39Xj1a.png) - QW will check that the chain of design items are able to be processed and fully signed off, when this is successful the github action will pass From 976105b9fc1ef3ff0b8c6ffe7dcba10b8a5d6aef Mon Sep 17 00:00:00 2001 From: tim-band Date: Thu, 19 Oct 2023 11:49:19 +0100 Subject: [PATCH 09/14] Update README.md Co-authored-by: Stef Piatek --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6808328..87b6a10 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ The QW allows users to track the different changes in design and development req ## Installation -The `qw` tool requires python 3.9 or greater, if your project is in python then we suggest adding it to the developer requirements. Otherwise may want to create a virtual environment for your python, one option is the [venv](https://docs.python.org/3.9/library/venv.html) module. +The `qw` tool requires python 3.9 or greater, if your project is in python then we suggest adding it to the developer requirements. Otherwise you may want to create a virtual environment for your python, one option is the [venv](https://docs.python.org/3.9/library/venv.html) module. For Unix: From 92defab66a99eb164f56140736a9ea200f266468 Mon Sep 17 00:00:00 2001 From: tim-band Date: Thu, 19 Oct 2023 11:50:16 +0100 Subject: [PATCH 10/14] Update README.md Co-authored-by: Stef Piatek --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 87b6a10..e29c826 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ qw init --repo github.com:username/reponame --service github > INFO: Please commit the files after you have finished your setup > INFO: Rulesets and branch protection added for branches matching "main" to "stefpiatek/dummy-medical-software" -If you have a different development flow than using the default branch, then edit the `qw` ruleset for the repository, adding extra branches to the ruleset (e.g. `develop`) +If you have a different development flow than pull requests into main/master then edit the `qw` ruleset for the repository, adding extra branches to the ruleset (e.g. `develop`) + + duplicate + + #### explanation + + Duplicate of #5 + ``` ## Versioning of QW items -The `qw freeze` function is used to save the current state of the qw items in github, and to ensure that the versions of items are updated if their information has changed. +The `qw freeze` function is used to save the current state of the qw items in github, and to ensure that the versions of items are updated if their +information has changed. This should be run regularly, which will update or add to the `.qw` directory. These changes should be committed and added to the main development branch by a pull request as a [Non QW item](#non-qw-items). @@ -235,7 +284,8 @@ An example incrementing a tag upon update: > > Would you like to increment the version? (y/n): > INFO: Updated tag to "qw-v2" -> INFO: There are 2 design outputs that link to this Design Input, please ensure one of them has the "qw-v2" tag if it resolves the updated information +> INFO: There are 2 design outputs that link to this Design Input, please ensure one of them has the "qw-v2" tag if it resolves the updated +> information > > - https://github.com/stefpiatek/dummy-medical-software/pull/7 > - https://github.com/stefpiatek/dummy-medical-software/pull/12 @@ -256,11 +306,15 @@ Example response when the change is trivial and does not warrant a change in the When you're ready to update the documentation in your Quality Management System (QMS), you can use the QW tool's `release` command. Running this will: -- Ensure that all issues and pull requests have been marked with `qw-ignore` or one of the `qw-` item tags, raising an error (and stopping) to ensure all items are tagged +- Ensure that all issues and pull requests have been marked with `qw-ignore` or one of the `qw-` item tags, raising an error (and stopping) to ensure + all items are tagged - Ensure that all QW items have versions -- Ensure the entire chain `design validation -> design verification -> design output -> design input -> user need` is consistent with QW rules, starting from the furthest stage of QW items. So if there is no `design validation`, then the chain will start from `design verification`. If there was only a `user need` and `design input`s, then only these would be validated +- Ensure the entire chain `design validation -> design verification -> design output -> design input -> user need` is consistent with QW rules, + starting from the furthest stage of QW items. So if there is no `design validation`, then the chain will start from `design verification`. If there + was only a `user need` and `design input`s, then only these would be validated - Create word documents based on the QW template for export -- [name=Stef] Optionally? Create an html page that shows a burndown graph for each of the QW item types, showing the number completed and outstanding over time. Would this be useful? +- [name=Stef] Optionally? Create an html page that shows a burndown graph for each of the QW item types, showing the number completed and outstanding + over time. Would this be useful? ```shell qw release qms_docs @@ -274,12 +328,14 @@ qw release qms_docs # FAQ and common issues - Can I import an existing project into QW - - There's nothing stopping this, though each issue and pull request would need to match the required format, and be tagged appropriately by the time you'd like to run a release. This may be a reasonable amount of work and we expect issues may need to be created. + - There's nothing stopping this, though each issue and pull request would need to match the required format, and be tagged appropriately by the + time you'd like to run a release. This may be a reasonable amount of work and we expect issues may need to be created. - # Open questions -- Which document parts are the most useful for export, and would we want the user to be able to edit the template (update styles and placeholder text?) +- Which document parts are the most useful for export, and would we want the user to be able to edit the template (update styles and placeholder + text?) - Would the burndown chart be useful to get an overview for development? - Gate who can authorise a PR, or can anyone? - Should we include a change request at this stage, or keep it with the risk management side of things From 5ada4d5f3249eaea7d61ce84bdaf539150d43417 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Fri, 20 Oct 2023 09:57:44 +0100 Subject: [PATCH 12/14] Use "requirement" instead of "design input" Seems to be what's being used in example documentation and is easier to understand from other contexts --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 66b0df8..366db3d 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ qw init --repo github.com:username/reponame --service github > INFO: A ".qw" directory has been created > INFO: Github actions for qw have been added to your ".github" directory -> INFO: Templates added to your ".github" directory: "User need", "Design input", "Design output", "Pull request" +> INFO: Templates added to your ".github" directory: "User need", "Requirement", "Design output", "Pull request" > INFO: Please commit the files after you have finished your setup > INFO: Rulesets and branch protection added for branches matching "main" to "stefpiatek/dummy-medical-software" @@ -121,7 +121,7 @@ QW creates identifiers for User Needs and Requirements. | User Need | `URS-U${user need number}` | URS-U001 | | Requirement | `REQ-${component short code}-${requirement number}` | REQ-SWR-0001 | -QW initialises with a `System` component for design inputs (used for generating a unique identifier, short code value is `X`). +QW initialises with a `System` component for requirements (used for generating a unique identifier, short code value is `X`). You can add extra components to the configuration by editing the `/.qw/components.csv` ``` @@ -157,7 +157,7 @@ QW uses existing issues and pull requests to track the different design and deve - The first comment of this issue will be used by `qw` for tracking, but you can edit anything manually after the `Other information` header and this will not interfere with the tool -### Design inputs +### Requirements - In your github repository, Add a new issue, selecting the User needs template ![](https://hackmd.io/_uploads/Syo1w1oy6.png) @@ -177,7 +177,7 @@ QW uses existing issues and pull requests to track the different design and deve - User maintenance - Regulatory - Hit `Submit new issue` and theissue will be rendered like this: - ![](https://hackmd.io/_uploads/H1-xiDBWT.png) + ![](https://hackmd.io/_uploads/Bycax6yfp.png) - Note that the `design-component-d` has been added as "Drug dosage" was added as a component type with a short code of `D`. - The first comment of this issue will be used by `qw` for tracking, but you can edit anything manually after the `Other information` header and this will not interfere with the tool @@ -190,13 +190,13 @@ QW uses existing issues and pull requests to track the different design and deve ![](https://hackmd.io/_uploads/BkYpd7ikp.png) - If the `qw-ignore` tag is added, then this PR does is not related to the medical device aspect of the software - In this example, the pull request contains the design outputs and design verification. These can be added seperately, where the design verification - would also be linked to the design input. + would also be linked to the requirement. ![](https://hackmd.io/_uploads/ryp39Xj1a.png) - QW will check that the chain of design items are able to be processed and fully signed off, when this is successful the github action will pass ![](https://hackmd.io/_uploads/H1Ix67i16.png) - QW requires a pull request that is labelled as a `design-validation` or `design-verification` to have at least one automated test that targets a - specific `design-output`, `design-input` or `user-need` + specific `design-output`, `requirement` or `user-need` - Tests are tracked manually in `.qw/test_mapping.csv` where multiple issues are separated by `;`, in the following structure test name | issue(s) targeted -- | -- @@ -270,7 +270,7 @@ An example incrementing a tag upon update: > Running WQ freeze > Found 47 QW items > -> INFO: Design Input https://github.com/stefpiatek/dummy-medical-software/issues/6 has been updated since last saved +> INFO: Requirement https://github.com/stefpiatek/dummy-medical-software/issues/6 has been updated since last saved > > Previous data: > @@ -284,7 +284,7 @@ An example incrementing a tag upon update: > > Would you like to increment the version? (y/n): > INFO: Updated tag to "qw-v2" -> INFO: There are 2 design outputs that link to this Design Input, please ensure one of them has the "qw-v2" tag if it resolves the updated +> INFO: There are 2 design outputs that link to this Requirement, please ensure one of them has the "qw-v2" tag if it resolves the updated > information > > - https://github.com/stefpiatek/dummy-medical-software/pull/7 @@ -298,7 +298,7 @@ Example response when the change is trivial and does not warrant a change in the > ... > Would you like to increment the version? (y/n): -> INFO: Tag kept at "qw-v1", data for the Design Input has been updated to the current state +> INFO: Tag kept at "qw-v1", data for the Requirement has been updated to the current state > ... ### Creating a documentation release @@ -309,9 +309,9 @@ Running this will: - Ensure that all issues and pull requests have been marked with `qw-ignore` or one of the `qw-` item tags, raising an error (and stopping) to ensure all items are tagged - Ensure that all QW items have versions -- Ensure the entire chain `design validation -> design verification -> design output -> design input -> user need` is consistent with QW rules, +- Ensure the entire chain `design validation -> design verification -> design output -> requirement -> user need` is consistent with QW rules, starting from the furthest stage of QW items. So if there is no `design validation`, then the chain will start from `design verification`. If there - was only a `user need` and `design input`s, then only these would be validated + was only a `user need` and `requirement`s, then only these would be validated - Create word documents based on the QW template for export - [name=Stef] Optionally? Create an html page that shows a burndown graph for each of the QW item types, showing the number completed and outstanding over time. Would this be useful? From 1f0dc208cd2b81386ae97003b9a4aa36652eac64 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Fri, 20 Oct 2023 10:13:46 +0100 Subject: [PATCH 13/14] Shorten lines --- README.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 9ecd753..337cf5e 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,26 @@ # Proposed Quality Workflow (QW) user guide - release 1 -The Quality Workflow tool (QW) aims to help reduce the friction in creating and maintaining traceability matrices (later release could target hazards and risks). +The Quality Workflow tool (QW) aims to help reduce the friction in creating and maintaining traceability matrices +(later release could target hazards and risks). # Background and use-case -Within medical device software there are several design and development stages that should be tracked, versioned and a traceability matrix is a standard way of presenting this information. The Quality Management System used in WEISS is document based, which requires substantial manual effort in tracking linkages, updating of versions and ensuring that all approvals are current. +Within medical device software there are several design and development stages that should be tracked, +versioned and a traceability matrix is a standard way of presenting this information. +The Quality Management System used in WEISS is document based, which requires substantial manual effort in tracking linkages, +updating of versions and ensuring that all approvals are current. -The QW allows users to track the different changes in design and development requirements, outputs, verification and validations. These different stages are linked together using github or gitlab as part of the normal development process. QW also will ensure that versioning of items are updated if their contents have changed, and notify when manual verification should be rerun due to changes in requirements or outputs. +The QW allows users to track the different changes in design and development requirements, outputs, verification and validations. +These different stages are linked together using github or gitlab as part of the normal development process. +QW also will ensure that versioning of items are updated if their contents have changed, +and notify when manual verification should be rerun due to changes in requirements or outputs. # Setup ## Installation -The `qw` tool requires python 3.9 or greater, if your project is in python then we suggest adding it to the developer requirements. Otherwise you may want to create a virtual environment for your python, one option is the [venv](https://docs.python.org/3.9/library/venv.html) module. +The `qw` tool requires python 3.9 or greater, if your project is in python then we suggest adding it to the developer requirements. +If not, you may want to create a virtual environment for your python, one option is the [venv](https://docs.python.org/3.9/library/venv.html) module. For Unix: @@ -48,10 +56,11 @@ qw init --repo github.com:username/reponame --service github > INFO: Please commit the files after you have finished your setup > INFO: Rulesets and branch protection added for branches matching "main" to "stefpiatek/dummy-medical-software" -If you have a different development flow than pull requests into main/master then edit the `qw` ruleset for the repository, adding extra branches to the ruleset (e.g. `develop`) +If you have a different development flow than pull requests into main/master then edit the `qw` ruleset for the repository, +adding extra branches to the ruleset (e.g. `develop`) You can omit `--service github` if the repo is at `github.com` (as in @@ -61,7 +70,7 @@ repository configured as the git remote named `upstream`. #### Setup Personal Access Token - Follow - the [github instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + the [GitHub instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) we suggest the following configuration options: | field | value, user defined values defined by `${...}` | From 8e480c93688617ef001cda2c2e6fe8e77784f5c5 Mon Sep 17 00:00:00 2001 From: Stef Piatek Date: Fri, 20 Oct 2023 16:36:14 +0100 Subject: [PATCH 14/14] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 337cf5e..2983116 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ Drug dosage,D,Drug dosage calculation module. ``` ```shell -qw config --update +qw config --update-remote ``` > INFO: Added "Drug dosage (D)" to local components, ensure that the updated file is committed.