Improving link management under CI/CD

[wendellpiez]

User Story:

The CI/CD process includes a script to perform link checking. This is very useful, ensuring that the OSCAL web site does not present users with broken links.

But this becomes an impediment when a link breaks. When a linked page or site is no longer available, our builds fail until the offending link is removed or replaced. However, a developer making a PR frequently does not have knowledge or authority for changing a link in a page having nothing to do with the actual work in the branch.

Currently (at time of writing) this is happening with two links, both in the file build/README.md:

• http://releases.ubuntu.com/18.04.4/
• http://schematron.com

Goals:

1. Repair any pages with broken links that currently prevent building
2. Provide support to team members to rebase dev branches so they also will build
3. Clarify editorial policy: when and for what purposes should links be included at all, and how do we ensure that links are to pages that are unlikely to move or disappear? If a link does break, how should we repair it or otherwise mitigate the issue, so that a build will pass validations under CI/CD?
4. Determine a strategy going forward for maintaining links with less overhead. This could include a capability for adding a link to a do-not-check list but also clear rules on which links can be added and why. Or possibly link checking should not be performed for all PRs, but only some of them (e.g. those devoted to web site maintenance).

Dependencies:

None known.

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

[wendellpiez]

For the Ubuntu link, my browser is redirected here: http://old-releases.ubuntu.com/releases/18.04.4/. I will see if changing to this addresses the problem.

The Schematron link returns a page reporting a database connection error. (It is interesting that this is detected as a failed link.) One possible alternative would be the Github repo of the (de facto) reference implementation: https://github.com/Schematron/

I will push up changes next and make a PR; if it passes the link checker we can look at the edits.

Next: rebasing other branches (at least those behind pending PRs); any policy considerations going forward.

[david-waltermire]

We fixed the broken links, but we still need to address a more permanent mechanism for managing broken links. The approach going forward needs to allow for minimal disruption to the typical developer working in the repo.

[aj-stein-nist]

Will fix this in #1208 now that Metaschema equivalent of tooling improvement was merged, fixed, and approved by Dave.