Feature: Show version of content in export

[johanenglund]

Description

As an auditor of exported requirement (e.g. in PDF format) I need to see version of the document to record evidence.

This can currently be solved by having a manually maintained version field in an sdoc but it is not optimal as updating it can easily be forgotten.

When a new release of the requirements is done we create a version tag in git according to semantic versioning (1.2.3). Preferably we would like a way to get this tag and/or git hash into the strictdoc export.

Problem

How to get repository information into export artifact?

Solution

?

[johanenglund]

To solve this I'm dynamically creating an .sdoc at build time from git repo info that look like below. The idea is that this file is to be included at top or bottom of all requirement .sdocs. Only problem now is that I have to copy this temporary file into the requirement repo for it to work which is not nice.

[DOCUMENT]
TITLE: Requirement repository version

[TEXT]
STATEMENT: >>>
Branch '3-quality', hash bbdca5a, 2024-11-22T18:48:37+01:00
<<<

Is there any way to reference a path based on an environment variable in the [DOCUMENT_FROM_FILE] tag? For CMake I would want to do e.g.

set(ENV{PROJECT_BINARY_DIR} "${PROJECT_BINARY_DIR}")

and then

[DOCUMENT_FROM_FILE]
FILE: $PROJECT_BINARY_DIR/requirement_version.sdoc

[stanislaw]

I didn't have enough spare cycles to think about this. Just an intermediate comment: The Project Statistics screen prints the Git version already, so the functionality is there. We just need to come with a good place to have it for each exported documents in HTML and PDF.

[johanenglund]

The git hash in project statistics is good. There's also a field for "Last modification of project data" that could have been used to see if the requirements in hand are older or newer than previous ones. So far I've not managed to figure out what it gets that timestamp from though.

Getting a branch/tag in there also would make it a lot better at least for our process since a version number tag indicates an official release, which cannot be discerned from a git hash alone (could just be a draft copy).

[stanislaw]

{
    "Key":"Last modification of project data",
    "Value": view_object.traceability_index.strictdoc_last_update.strftime("%Y-%m-%d %H:%M:%S"),
  },

The strictdoc_last_update is taken from calculating all project file timestamps and finding the maximum one. Now that we are talking through this, I realize that I was biased/shortsighted when I created this metric because I was testing it against StrictDoc's own documentation being its sole writer. A trivial but important observation: the modification date for a document file cannot be a reliable source because a document can stay the same but some other document can change links to it and therefore the content of the unmodified document will be also changed when it is regenerated, or I can do a touch on this document and the changed date will also not make sense.

A more reliable way will probably be to get the time of the last commit of the whole Git repo, would you agree? Because otherwise it is pretty hard to track which changes could contribute to a freshness of a given document.

---

I think we could add the dynamic date to document's meta information as follows:

[DOCUMENT]
TITLE: Technical Note: DO-178C requirements tool requirements
VERSION: @GIT_VERSION
DATE: @GIT_COMMIT_DATE

StrictDoc could then do some interpolation and call into Git to get these values.

@GIT_VERSION
@{GIT_VERSION}
$GIT_VERSION
#GIT_VERSION
#{GIT_VERSION}

I am not decided which option would be the best and most Pythonic one. Let me know what you think.

[johanenglund]

The timestamp of last commit is what I was expecting to see, as it seemed to be related to the git hash, and it would be more correct for my use case. But what about people that don't use git for this? (I'm assuming there are corner cases for everything!)

Would you consider including the branch/tag somehow too?

git rev-parse --abbrev-ref HEAD

[stanislaw]

Would you consider including the branch/tag somehow too?

Sure!

---

To summarize:

• I am going to introduce this @GIT_VERSION interpolation.
• Right now, the document meta fields are not customizable, so we have to have them fixed, see https://strictdoc.readthedocs.io/en/stable/strictdoc_01_user_guide.html#document
• I can do something like this:

[DOCUMENT]
TITLE: Foo
VERSION: @GIT_VERSION, @GIT_BRANCH
DATE: @GIT_LAST_COMMIT_DATE

then StrictDoc would interpolate.

Is this how you would like it to be or we should have more fields? Please suggest a proposal.

I could start working on this as my next task this evening :smile:

[johanenglund]

This would be perfect for me and I assume it would also work well for those that don't use git.