[collab] traceability poc/integration #78380

nashif · 2024-09-13T09:16:44Z

Note: This is a collab branch change and will be work in progress for a while before it is submitted for final review into main. So unless you are involved in the collab branch work or interested in this effort in particular, probably you do not want to spend much time on this now.

poc for integration of reqmgmt into documentation and tracing tests to requirements using doxygen and mlx traceability plugin.

not much to see here for now...

zephyrbot · 2024-09-13T09:17:43Z

The following west manifest projects have been modified in this Pull Request:

Name	Old Revision	New Revision	Diff
reqmgmt	N/A	zephyrproject-rtos/reqmgmt@`1f96a9f` (main)	N/A

Note: This message is automatically posted and updated by the Manifest GitHub Action.

simhein · 2024-09-17T07:08:57Z

.github/workflows/doc-build.yml

-        # API documentation coverage
-        python3 -m coverxygen --xml-dir  doc/_build/html/doxygen/xml/ --src-dir include/ --output doc-coverage.info
-        # deprecated page causing issues
-        lcov --remove doc-coverage.info \*/deprecated > new.info
-        genhtml --no-function-coverage --no-branch-coverage new.info -o coverage-report
-
    - name: compress-docs
      run: |
        tar --use-compress-program="xz -T0" -cf html-output.tar.xz --directory=doc/_build html
        tar --use-compress-program="xz -T0" -cf api-output.tar.xz --directory=doc/_build html/doxygen/html
-        tar --use-compress-program="xz -T0" -cf api-coverage.tar.xz coverage-report

    - name: upload-build
      uses: actions/upload-artifact@v4
      with:
        name: html-output
        path: html-output.tar.xz

-    - name: upload-api-coverage
-      uses: actions/upload-artifact@v4
-      with:
-        name: api-coverage
-        path: api-coverage.tar.xz
-


Is there a specific reason why the api coverage was removed? Or was it to keep the overhead minimal for the first draft of this PR?

just temporary to remove noise

Is it really a problem to keep it though? Not sure it actually generates "noise", does it?

simhein · 2024-09-17T08:23:22Z

doc/requirements/create_req.py

+            parse_nodes(d['NODES'], grouped)
+    return grouped
+
+def parse_dng_csv(filename):


That import wouldn't work with any of the strict doc exports right now. Is this intended to be left there to be extended in the future?

will remove

simhein · 2024-09-17T08:28:18Z

doc/zephyr.doxyfile.in

@@ -1179,7 +1184,7 @@ SOURCE_BROWSER         = NO
 # documentation.
 # The default value is: NO.

-INLINE_SOURCES         = NO
+INLINE_SOURCES         = YES


I assume this was activated to include the test function bodies into the doxygen documentation am I right?

dont remember tbh, I assume yes.

simhein · 2024-09-17T08:32:44Z

doc/_doxygen/groups.dox

+@defgroup kernel_memprotect_tests Memory Protection
+@ingroup all_tests
+@{
+@}


Is there a reason why group is defined in the group.dox and not like the others in the source file?

those exist in multiple places and tests, so putting this is a neutral place here.

simhein · 2024-09-17T08:43:55Z

doc/zephyr.doxyfile.in

+                         @ZEPHYR_BASE@/subsys/testsuite/ztest/include/ \
+			 @ZEPHYR_BASE@/tests/kernel/semaphore/ \
+              @ZEPHYR_BASE@/tests/kernel/threads/ \
+			 @ZEPHYR_BASE@/tests/kernel/mutex/ \
+                         @ZEPHYR_BASE@/kernel/sem.c \
+			 @ZEPHYR_BASE@/kernel/thread.c \
+			 @ZEPHYR_BASE@/kernel/sched.c \
+			 @ZEPHYR_BASE@/doc/requirements/requirements.dox


Adding the sources manually in this case is for testing purpose and the PoC?

yes, this is to get traceability to implementation.

simhein · 2024-09-17T08:48:40Z

include/zephyr/arch/arc/v2/arcv2_irq_unit.h

+ * Sets the IRQ line @p irq to trigger an interrupt based on the level or the
+ * edge of the signal. Valid values for @p trigger are _ARC_V2_INT_LEVEL and


Shouldn't we bring back these directly to the main branch instead of the collab branch if these tags are wrong?

they are already, there is a PR #78387

simhein · 2024-09-17T12:26:18Z

Looks good to me for the poc integration

simhein · 2024-09-24T07:55:49Z

I think if we can get rid of the compliance checks errors this batch could be merged to the branch.

An example for creating traceability between tests and requirements. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

nashif · 2024-09-26T21:26:05Z

I think if we can get rid of the compliance checks errors this batch could be merged to the branch.

done

simhein · 2024-09-27T09:27:43Z

MAINTAINERS.yml

+  maintainers:
+    - nashif


You can add me as a maintainer as well if you want, or as collaborator.

Pull requirements in so we can convert them to dox and integrate with doxygen. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

Script to convert requirements to dox. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

Integrate into doc workflow. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

simhein · 2024-10-21T13:22:30Z

@nashif should we merge this to move forward with the collab branch? Also should we activate the api-coverage generation again to not forget about it in a later stage?

kartben

making my comments non-blocking -- this looks like this going in the right direction :)

kartben · 2024-10-21T13:34:48Z

.github/workflows/doc-build.yml


    - name: west setup
      run: |
        west init -l .

+    - name: prcoess requirements


Suggested change

- name: prcoess requirements

- name: process requirements

kartben · 2024-10-21T13:36:00Z

.github/workflows/doc-build.yml

-        # API documentation coverage
-        python3 -m coverxygen --xml-dir  doc/_build/html/doxygen/xml/ --src-dir include/ --output doc-coverage.info
-        # deprecated page causing issues
-        lcov --remove doc-coverage.info \*/deprecated > new.info
-        genhtml --no-function-coverage --no-branch-coverage new.info -o coverage-report
-
    - name: compress-docs
      run: |
        tar --use-compress-program="xz -T0" -cf html-output.tar.xz --directory=doc/_build html
        tar --use-compress-program="xz -T0" -cf api-output.tar.xz --directory=doc/_build html/doxygen/html
-        tar --use-compress-program="xz -T0" -cf api-coverage.tar.xz coverage-report

    - name: upload-build
      uses: actions/upload-artifact@v4
      with:
        name: html-output
        path: html-output.tar.xz

-    - name: upload-api-coverage
-      uses: actions/upload-artifact@v4
-      with:
-        name: api-coverage
-        path: api-coverage.tar.xz
-


Is it really a problem to keep it though? Not sure it actually generates "noise", does it?

kartben · 2024-10-21T13:36:31Z

doc/zephyr.doxyfile.in

+                         @ZEPHYR_BASE@/subsys/testsuite/ztest/include/ \
+			 @ZEPHYR_BASE@/tests/kernel/semaphore/ \
+              @ZEPHYR_BASE@/tests/kernel/threads/ \
+			 @ZEPHYR_BASE@/tests/kernel/mutex/ \
+                         @ZEPHYR_BASE@/kernel/sem.c \
+			 @ZEPHYR_BASE@/kernel/thread.c \
+			 @ZEPHYR_BASE@/kernel/sched.c \
+			 @ZEPHYR_BASE@/doc/requirements/requirements.dox


mixed tabs/spaces

kartben · 2024-10-21T13:59:24Z

doc/requirements/create_req.py

+        for r in grouped.keys():
+            comp = grouped[r]
+            counter += 1
+            req.write(f"\n@section REQSEC{counter} {r}\n\n")


suggest to use a different approach to generate the REQSECXXX name, as you probably don't want it to change unnecessarily. I.e. right now http://localhost:8081/Requirements.html#REQSEC1 links to "Hardware Architecture Interface" for me, and I might end up sharing this link thinking it points to this particular section, but it can break at any time
While not perfect, probably better to use_lowercase_and_underscore_version_of_the_title as the section name?

nashif · 2024-10-21T14:37:08Z

Is it really a problem to keep it though? Not sure it actually generates "noise", does it?

the introduction of the new tags does intefere with the coverage, I need to look into it in details later and re-enable.

zephyrbot added manifest manifest-reqmgmt DNM This PR should not be merged (Do Not Merge) labels Sep 13, 2024

nashif changed the base branch from main to collab-safety September 13, 2024 09:17

nashif force-pushed the topic/req/traceability branch 3 times, most recently from 329dd5e to dfa03e5 Compare September 13, 2024 11:07

nashif requested a review from simhein September 13, 2024 12:28

nashif force-pushed the topic/req/traceability branch from dfa03e5 to cd18e43 Compare September 13, 2024 12:32

simhein reviewed Sep 17, 2024

View reviewed changes

nashif force-pushed the topic/req/traceability branch from cd18e43 to 1c10bf4 Compare September 17, 2024 09:48

nashif force-pushed the topic/req/traceability branch from 1c10bf4 to e77668a Compare September 17, 2024 13:01

tests: kernel: add verification tag for tests

6917ab1

An example for creating traceability between tests and requirements. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

nashif force-pushed the topic/req/traceability branch from e77668a to 0f84417 Compare September 26, 2024 21:17

nashif removed the DNM This PR should not be merged (Do Not Merge) label Sep 26, 2024

nashif marked this pull request as ready for review September 26, 2024 21:26

nashif assigned simhein Sep 26, 2024

zephyrbot added area: Documentation Infrastructure area: Process area: Continuous Integration area: Kernel labels Sep 26, 2024

zephyrbot requested review from andyross, carlescufi, ceolin, cfriedt and dcpleung September 26, 2024 21:27

zephyrbot requested review from fabiobaltieri, gmarull, kartben, MaureenHelm, npitre, peter-mitsis, stephanosio and TaiJuWu September 26, 2024 21:27

simhein reviewed Sep 27, 2024

View reviewed changes

nashif added 3 commits September 27, 2024 05:32

manifest: pull requirements in

6b8900f

Pull requirements in so we can convert them to dox and integrate with doxygen. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

doc: add requirements into doxygen

a5bf6cd

Script to convert requirements to dox. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

ci: integrate requirements into docs workflow.

af88c89

Integrate into doc workflow. Signed-off-by: Anas Nashif <anas.nashif@intel.com>

nashif force-pushed the topic/req/traceability branch from 0f84417 to af88c89 Compare September 27, 2024 09:32

zephyrbot added the DNM This PR should not be merged (Do Not Merge) label Sep 27, 2024

simhein approved these changes Sep 27, 2024

View reviewed changes

nashif removed the DNM This PR should not be merged (Do Not Merge) label Sep 27, 2024

kartben approved these changes Oct 21, 2024

View reviewed changes

nashif merged commit 1396bc2 into zephyrproject-rtos:collab-safety Oct 21, 2024
26 of 27 checks passed

nashif deleted the topic/req/traceability branch October 21, 2024 14:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[collab] traceability poc/integration #78380

[collab] traceability poc/integration #78380

nashif commented Sep 13, 2024 •

edited

Loading

zephyrbot commented Sep 13, 2024

simhein Sep 17, 2024

nashif Sep 17, 2024 •

edited

Loading

kartben Oct 21, 2024

simhein Sep 17, 2024

nashif Sep 17, 2024

simhein Sep 17, 2024

nashif Sep 17, 2024

simhein Sep 17, 2024

nashif Sep 17, 2024

simhein Sep 17, 2024

nashif Sep 17, 2024

simhein Sep 17, 2024

nashif Sep 17, 2024

simhein commented Sep 17, 2024

simhein commented Sep 24, 2024

nashif commented Sep 26, 2024

simhein Sep 27, 2024

simhein commented Oct 21, 2024

kartben left a comment

kartben Oct 21, 2024

kartben Oct 21, 2024

kartben Oct 21, 2024

kartben Oct 21, 2024

nashif commented Oct 21, 2024

		* Sets the IRQ line @p irq to trigger an interrupt based on the level or the
		* edge of the signal. Valid values for @p trigger are _ARC_V2_INT_LEVEL and

[collab] traceability poc/integration #78380

[collab] traceability poc/integration #78380

Conversation

nashif commented Sep 13, 2024 • edited Loading

zephyrbot commented Sep 13, 2024

Choose a reason for hiding this comment

nashif Sep 17, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

simhein commented Sep 17, 2024

simhein commented Sep 24, 2024

nashif commented Sep 26, 2024

Choose a reason for hiding this comment

simhein commented Oct 21, 2024

kartben left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nashif commented Oct 21, 2024

nashif commented Sep 13, 2024 •

edited

Loading

nashif Sep 17, 2024 •

edited

Loading