Skip to content

Link draft SQA elements to the SQAP's source at their revision - #91

Merged
slominskir merged 2 commits into
mainfrom
draft-sqap-links
Nov 18, 2026
Merged

slominskir merged 2 commits into
mainfrom
draft-sqap-links

Conversation

@slominskir-coding-agent

@slominskir-coding-agent slominskir-coding-agent Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

In the SQA Elements dialog, each element's § link went to the SQAP website under latest. The site's _redirects sends /latest/* to /v1.0.0/, the last released revision. SIM loads a draft revision (draft 8905d54 after 1.0.0), so many links pointed at text that doesn't have the element:

  • Ratings recorded, ACS dependencies recorded, Installed version shown, Read-only install and Two maintainers link to sections that exist in v1.0.0, but its tables have no such rows. "Purpose and use documented" has an older row there.
  • The four dependency elements link to #615-required-sqa-elements, but v1.0.0 has no section 6.1, so they land at the top of section 6.

Now:

  • Element links: sqa_elements_sql.py links a draft's elements to the SQAP's source on code.jlab.org at the draft's commit, such as https://code.jlab.org/acc/iac/docs/sqap/-/blob/8905d54/docs/04-software-development-life-cycle.md#446-maintenance. GitLab gives each heading the same anchor as the website. I checked every anchor these links use with GitLab's Markdown API: #441-requirements, #446-maintenance, #615-required-sqa-elements, #44-life-cycle-stages, #43-software-control-levels and #431-ops-impact to #434-recording-the-control-level.
  • Released revisions: they still link to their own folder on the website (/v2.0.0/…), so these links move to the website once SIM loads SQAP 2.0.0 (Load the released SQAP revision's SQA elements in place of the draft's #79).
  • The dialogs' section links: the SQA Elements dialog's "SQAP §4.4" and the Risk & SQA Assessment dialog's "SQAP §4.3" now come from the loaded elements, instead of always going to latest.
  • The user guide's links to 4.3.1–4.3.4 (Ops Impact, Code Complexity, control level table, recording the control level): v1.0.0 has a 4.3 but none of these subsections. The guide is static and published with each release, so it names the revision this release loads, …/-/blob/8905d54/docs/04-software-development-life-cycle.md#431-ops-impact and so on, and says why the links go to code.jlab.org. When SIM loads another SQAP revision (Load the released SQAP revision's SQA elements in place of the draft's #79), these four links need updating with it.
  • 03_sqa_elements.sql is regenerated, with only SECTION_URL changing. The user guide says where the links go.

Release notes

  • SQAP links go to the revision SIM loads: while SIM loads a draft SQAP, each element's § link, the SQA Elements dialog's SQAP §4.4 link, the assessment dialog's SQAP §4.3 link and the user guide's links to 4.3.1–4.3.4 open the SQAP's source at that revision on code.jlab.org. Before, they went to the released v1.0.0, which lacks many of the elements and the 4.3 subsections

Oracle DB Migration Notes

Run on a database at 2.11.0, as SIM_OWNER:

  1. container/oracle/upgrade/2.11.1_sqap_draft_section_links.sql: updates SQA_ELEMENT.SECTION_URL of the 17 elements.

Checks

  • ./gradlew build: passes.
  • ./gradlew integrationTest against a new stack built from this branch: 92 tests, 0 failed. The new PagesIT.elementsLinkToTheSqapRevisionTheyCameFrom checks Two maintainers' link, the §4.4 link and the §4.3 link against the revision named in the dialog's footer. I reran the tests after the second commit.
  • Failing without the fix, and the upgrade script:
    1. On that stack I set SECTION_URL back to what 2.11.0 loads. The new test then failed: expected https://code.jlab.org/…/8905d54/…#446-maintenance but was https://pages.jlab.org/…/latest/…#446-maintenance.
    2. I ran the upgrade script: 17 rows updated, identical to a new database's. The test passed again.
  • uv run --locked zensical build --strict: no issues.
  • docker compose logs sim: the only errors come from the tests' rejection cases.
  • Not checked: opening the code.jlab.org links in a browser. The VM reaches code.jlab.org only through its API proxy, which confirmed both files exist at 8905d54.

Decisions

  • After the first version of this PR, the person asked to point the assessment's 4.3 links at the same revision, in this PR.
  • The person asked whether the links went to the old SQAP. Confirmed: latest redirects to v1.0.0. They chose to link the draft's source at its revision until SQAP 2.0.0 is released (sqap!12) and SIM loads it (Load the released SQAP revision's SQA elements in place of the draft's #79), over waiting for that release.
  • The upgrade script is named for 2.11.1, as a fix. Rename it if this ships in another version.

Prepared-by: Anthropic Claude Code:claude-opus-5-5

🤖 Generated with Claude Code

Each element in the SQA Elements dialog linked to its section on the
SQAP's website under "latest", which redirects to the last released
revision, 1.0.0. SIM loads a draft revision (8905d54 after 1.0.0), whose
tables have rows 1.0.0 lacks, such as Two maintainers, and whose section
6.1.5, holding the four dependency elements, 1.0.0 doesn't have at all,
so links landed on tables without their element or at the top of the
page.

sqa_elements_sql.py now links a draft's elements to the plan's source on
code.jlab.org at the draft's commit, where GitLab gives each heading the
website's anchor; a released revision still links to its own folder on
the website. The dialog's SQAP section 4.4 link follows the loaded
elements instead of always "latest". 03_sqa_elements.sql is regenerated,
and existing databases need
container/oracle/upgrade/2.11.1_sqap_draft_section_links.sql.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@slominskir-coding-agent slominskir-coding-agent Bot added the source::ai Prepared by an AI coding agent label Nov 18, 2026
@slominskir-coding-agent slominskir-coding-agent Bot added the source::ai Prepared by an AI coding agent label Nov 18, 2026
The Risk & SQA Assessment dialog's "SQAP section 4.3" link and the user
guide's links to 4.3.1 to 4.3.4 still went to the SQAP website's
"latest", the released 1.0.0, which has a 4.3 but none of those
subsections. The dialog's link now follows the loaded elements, as the
SQA Elements dialog's 4.4 link does. The user guide, published with each
release, names the revision this release loads (8905d54) and says why it
is on code.jlab.org.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@slominskir
slominskir merged commit 26a9082 into main Nov 18, 2026
7 checks passed
@slominskir
slominskir deleted the draft-sqap-links branch November 18, 2026 16:20
slominskir pushed a commit that referenced this pull request Nov 18, 2026
The SQAP (acc/iac/docs/sqap!22, revision 19bcfba) merged "Dependencies
on other ACS products recorded in the build files or README" into
"Dependencies recorded in the build files or README: acquired software
with its versions, and other ACS products, including their servers,
schemas and web services", and named the group of dependency elements
Dependencies instead of Acquired Software. A checklist now asks once for
the record of a product's dependencies, and shows it with the other
dependency elements; acs-dependencies-recorded is retired.

03_sqa_elements.sql is regenerated: 16 elements. Existing databases
need container/oracle/upgrade/2.11.1_sqap_dependencies_merged.sql,
which sets each element's row to what a new database loads, moves a
status recorded for the retired element to dependencies-recorded where
a product has none there, after listing the products that recorded the
two differently, and deletes the retired element. It also sets the
section links #91 changed, so it replaces that pull
request's unreleased 2.11.1_sqap_draft_section_links.sql: one script
for the release, with no order to get wrong.

The user guide's links to section 4.3 name the new revision.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@slominskir-coding-agent slominskir-coding-agent Bot mentioned this pull request Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

source::ai Prepared by an AI coding agent

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant