How can I manage changes?

The below is what we do to manage changes to Matrix.

The Process

Note: that's not necessarily the best way to do it, it depends on what kind of project you have and the size and experience of the development team, but for us this is highly efficient.

Backlog - ideas for changes

The ideas can come from multiple sources: it can be

internal ideas for new features or improvements
maintenance work, like a refactoring
requests from customers
bugs which were identified

All of these end up in our task management software (JIRA)

In the task management software we prioritize them. We plan in which they release they should go and link them to support tickets and create sub tasks if needed.

Decision to implement

As soon as we decide to implement such a backlog ticket we

create an item in a category CHANGE in the development project in Matrix from the ticket
modify the text of the CHANGE item to be the one we want to show in our release notes.
automatically have link from the backlog ticket to the CHANGE item in Matrix.

Note: The creation of the item in Matrix documents our approval (this action could be either limited to some people or you could add some approval label or quality gate in Matrix if you need more control)

Implementation - link to the source code

The implementation is starting from the backlog tickets.

The developer verifies if the tickets are linked to Matrix CHANGE items
If needed sub tasks are created.
Whenever we commit source code to our repository we have to provide a backlog ticket id. This way we have a complete traceability from all source code changes to development tickets and through the development tickets to the CHANGES in Matrix. This makes it impossible that changes to the code happen without trace in the ticketing software.

Note: for additional control you could also require a link to the CHANGE item when committing the tickets, but the link to the backlog ticket is more important from a practical point of view.

Documentation of changes in Matrix

All changes to a release are kept in folder in the Matrix development project in the CHANGE category. From these changes we create links into our design documentation (DHF):

if a change is a new feature we (in general) link it to some new design input (user or system requirement)
if a change is an improvement we (in general) link it to an existing design output (system requirement or software requirement)
if a change is a bug fix we might just link it to an existing or new test case

If we link a CHANGE to an existing item we update everything in Matrix down to the tests. This could be flagged with a label or gate field stating that the down traces have been updated and reviewed.

Testing of changes

In Matrix it is easy to find all the tests related to a folder containing some changes using the miracle query language, e.g. select a CHANGE item or folder and run this full text search: mrql:uplinkm=_this_ and category=TC

The above will finds all tests (TC) which have somehow and uplink to a CHANGE item.

We use the above query to define which tests initially need to be executed (of course we need to add some to cover possible side effects, but for a first test run or smoke test that's in general a good list).

Instructions for use and release notes

Release notes we can create directly from the CHANGES in Matrix

We also link from the changes in Matrix to the relavant chapter IFU (for that reason we maintain it in a wiki (confluence) and publish it as this website) . That way we can make sure everything is sufficiently documented.

Risk Management

At some point we will review all the CHANGE items for a new release and document that as part of our risk management file.

Final Review of Changes

We use labels to document that a CHANGE has been completely implemented.

First we set the DEV DONE and DOC DONE (when the development and document are completed), and afterwards we do a final design review to document the completion of risk assessment, traceability and such things

Now we can see that a product change has been completely implemented.

Summary

Doing the above we have a complete traceability

from a source of a change (e.g. a support desk ticket)
to the source code on one side (through the ticketing / agile development software),
to the design history file with the design input, output, tests and test results
to the IFU
to a release of the product

and the same back. There are literally no holes since all the links are enforced by reviews or software, and - that's the best thing - it takes almost no time to update and maintain the links.