SPIKE: Manage website content from separate repository

[aj-stein-nist]

User Story

As a NIST OSCAL developer, in order to more efficiently manage changes to the code and models separate of website content changes, I would like to evaluate making changes and deploying website content from a repo that is separate from usnistgov/OSCAL.

Goals

• Separate model changes in releases and tooling updates from unrelated website content changes
• Separate model changes and tooling updates from the publication of documentation for them on the website

Dependencies

No response

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.

(For reviewers: The wiki has guidance on code review and overall issue review for completeness.)

Revisions

No response

[aj-stein-nist]

@Compton-NIST, you have the wheel, you're driving this one.

[Compton-US]

Update:

• I am working on a quick prototype in OSCAL-Pages to remove all things not related to website. Goal is to see if we can publish to an alternate NIST pages site successfully without impact to the overall OSCAL project and site.
• @nikitawootten-nist is evaluating a path forward for reference content generation in OSCAL-Pages that would ultimately allow us to clean the main OSCAL project of all web and reference generation. If successful, this would be a "Phase 1" step, and a future "Phase 2" would allow us to revisit how/if we want to generate reference directly in OSCAL in some reusable way.
• @aj-stein-nist is going to check to see what the possibility is for using the OSCAL-Pages project as the content delivered for the current OSCAL site. If not possible, there are a few options we can discuss for moving forward, but they all have a different combination of Pros/Cons.

We also discussed putting this out to the community. Once we know whether the pages redirect is a possibility or not, we can communicate our options and see if there are strong opinions around any of them.

[aj-stein-nist]

* @aj-stein-nist is going to check to see what the possibility is for using the `OSCAL-Pages` project as the content delivered for the current OSCAL site.  If not possible, there are a few options we can discuss for moving forward, but they all have a different combination of Pros/Cons.

Sent email to the appropriate technical contact that leads pages.nist.gov to review symlink issue, discuss viability, and other considerations.

[Compton-US]

Update:

• OSCAL-Pages almost ready. Need to do one more round of cleanup.
• Also need to test this once Actions are enabled.
• Problems encountered around Hugo and the significant size of reference material. Pulled it out for now.
• Nikita is testing out a reference generation scheme that decouples it from the OSCAL and Pages projects.
• Still to come on how this fits together. If the reference generation looks viable, we'll talk more about how we can shift.

Ultimate goal is simplest possible OSCAL repo, with very little extra tooling, and focus on models for developers and participation by others. More to come.

[Compton-US]

Update:

• Draft PR for the pages only site.

• Generates HUGO site, checks links.

• An example of artifacts can be found here

• This does not attempt to publish.

• CI is streamlined into one workflow for the website.

• Still have the ci-cd "orchestrator" workflow, and the workflow to generate CI docs.

• I believe Nikita has the basics running for reference generation.

• We need to coordinate and discuss:

  • Linking pages site to reference site.
  • Publishing a test of the Pages site to NIST pages (potentially?)
  • Publishing a test of the Reference site to NIST pages.
  • Cleaning up the OSCAL repo, and what do we want to do there for a minimal reference?
  • Just for memory - current approach depends on ability to point OSCAL link to OSCAL-Pages - AJ sent info to pages contacts for evaluation.

Current feature branch workflow

[aj-stein-nist]

This was completed long ago, closing now.