Release Candidate Target Definition

[brian-ruf]

User Story:

As an OSCAL specification designer, I clearly understand what tasks must be performed to enable a formal "release candidate" of the catalog, profile, and implementation layer specifications.

Goals:

• Develop a clearly defined definition of "done" for a release candidate.
• Develop clearly defined tasks to achieve the defined "done" state.
• The release candidate must be scoped to allow the work to be completed by 4/19/2019.

Dependencies:

Dependencies for "done" will be identified as part of working this issue.

Issues to include in discussion are:

• We should consider a version approach (Versioning mechanism for OSCAL schemas #57).

Acceptance Criteria

• All core OSCAL Team members understand the definition of "done" for a release candidate. (even if they don't all agree on the definition)
• A clear set of tasks exist (in the form of new issues) to achieve the defined "done" state.

[wendellpiez]

Sprint 18 Progress Feb 28 2019

On Friday we made progress on scoping this problem. @howieavp76 took notes.

We could make further progress by each of us writing an outline for an RC, then consolidate these and refine?

[iMichaela]

02/28/2019

@howieavp76 will resend the notes from the Friday meeting. @brianrufgsa and @wendellpiez will review and identify the RC.

[wendellpiez]

Sprint 18 progress March 7 2019

@brianrufgsa and I have been discussing various issues bearing on what should be in the RC.

% complete: 25% (if notes count)

[brian-ruf]

3/7/2019 - @howieavp76 to create straw man target so that the team can review and provide feedback, by 3/11/2019.

[david-waltermire]

3/13/2019

@howieavp76 will post notes from the meeting a couple weeks ago containing the items that need to be completed ahead of a release. During the week of 3/18 @wendellpiez and @brianrufgsa will develop a list of issues needed to get all the items completed ahead of the release.

[howieavp76]

@david-waltermire-nist - notes posted below.
NIST - Working Notes 2-22-19.pdf

[david-waltermire]

3/18/2019

We need to refine the scope of the Milestone release.

• Do we include declarations or not? Leaning towards excluding declarations.
• The specific website updates that are needed.
• What artifacts (e.g., schema, examples) to include in the release?

@howieavp76 will post a markdown version of the working notes. @david-waltermire-nist will edit these notes into a refined Milestone release requirement set.

[howieavp76]

Release Candidate Meeting Notes

Date: Friday, February 22, 2019

Release Candidate Discussion

Characteristics of a Release Candidate

• If people are not involved, they should be able to understand at a sufficient level to start adopting it
• What do they need to know without hand holding?
• Clear syntax and documentation
• Availability of the schema
• Specifiy tooling and pre-requisites
• Solidify the syntax
• Solidify what is needed
• Solidify the documentation
• Skeletons/templates/seeding
• Use "model" as the noun for describing things
• Basics of what is needed to get started

What does stable mean?

• Relatively complete and functioning as a MVP
• Catalog, profile, and implementation layers
• Snapshot in time - will continue to evolve
• Useable set of features that are reasonably done
• Need to express whether this will be backwards compatible or subject to future change
• Might rename or repurpose things
• Focus on additive changes v/s subtractive to ensure backwards compatibility
• Work to minimize disruptive change
• Tag the release as "pre-alpha"
• Need a way to revision it and tag the current state of the repository
• Make the catalog format as stable as we can
• Namespaces - stick with a single namespace (no namespace in JSON or YAML, want to normalize and stay uniform, simplest to adopt)

Timeline

• Milestone release in 3 months (end of May)
  • Website updates and documentation workflow (Howerton)
    • Best practice list
    • Package contents
    • Pre-requisites
    • Value Chain - walkthrough (look @brians presentation, abstract it)
    • Auto-publish documentation
  • Generalize resource concept as backmatter: replace current reference with new implementation
  • Update profile examples to validate to the new profile schema
  • Sync the document metadata for catalogs, profiles, and implementation
  • Test the declaration model for catalogs
• 2nd milestone release (TBD)
  • Document signing
  • Implementation module
  • Referential integrity (external links/resources)
  • Testing tools
  • Build declaration model to add constraints to other model or standards

What models do we release?

• Catalog
• Profile

Parking Lot

• Document history
• NIST 800-53 rev5 content (interim release when ready)
• Re-factor metamodel around references (external) and attachments (go with it)

Go to market strategy

• Purpose
  • To allow third parties to get real-world experience using OSCAL models
  • Review initial content to allow feedback for continuous improvement
  • Promote early adoption of OSCAL tool vendors and content creators
  • Preparation for the release of 800-53 rev5 and enabling organizations to adopt machine readable formats
• Audience
  • Tool developers
  • Content authors
• Marketing
  • Press release
  • NIST Bulletin
  • Webinars
  • Speaking Engagements
  • Partners - FedRAMP
  • Vendor Outreach - targeted and private
  • Most complete XML format, only JSON format

MVP Discussion

• Basic terminology list (on the website)
• Downloadable ZIP file
  • XML and JSON schemas for the released models
  • Content examples (illustrative)
  • 800-53 catalog and profile examples
  • Tooling and documentation on "how to use"
    • Schematron
    • Convertor tool

Exclusions from the MVP

• Metaschema
• Implementation/security plans

[howieavp76]

Posted in Markdown format

[iMichaela]

03/21/2019

@howieavp76 posted the list above. @brianrufgsa is not available this week. @wendel and @brianrufgsa will work on it next week.

[iMichaela]

03/28/2019

@wendel and @brianrufgsa will work on it early next week.

[brian-ruf]

4/4/2019 - @brianrufgsa and @david-waltermire-nist to finalize list after status meeting today.
Will post final list here when ready, and then discuss next steps with team. (Gaps will be addressed as separate issues.)

[iMichaela]

04/11/2019

The list was created and will be re-posted here by @brianrufgsa or @david-waltermire-nist . The list needs review as part of the Sprint acceptance.

[brian-ruf]

Ref #	Target	Current & Working	Gap	Lead (who)
1	Bring Catalog and Profile Metaschema to a stable initial state	Generally in good shape		Wendell
1.1	Metadata Metaschema	Updates complete. Just needs some additional testing/validation.		Wendell
1.2	Resource Metaschema	Updates complete. Just needs some additional testing/validation.		Wendell
1.3	Catalog Metaschema	Updates complete. Just needs some additional testing/validation.		Wendell
1.4	Profile Metaschema	Updates complete. Just needs some additional testing/validation.		Wendell
1.5	Import Capability (ie Metadata into Catalog)	Updates complete. Just needs some additional testing/validation.		Wendell
1.6	Ensure namespaces are aligned	Updates complete. Just needs some additional testing/validation.		Wendell
1.7	Build Out Schema documentation and examples within metaschema files.		Every element has a description. Every assembly must have an example. Every field and flag must appear in at least one example (even if it's an assembly description)	Wendell (Needs help)
2	CI/CD Pipeline			Travis
2.1	JSON and XML Schemas	Updates complete. Just needs significant additional testing/validation.	Will happen as part of CI/CD pipeline.	Script
2.2	JSON <-> XML Converters	Updates complete. Just needs significant additional testing/validation.	Will happen as part of CI/CD pipeline.	Script
2.3	Syntax Documentation (HTML Files)	Mechanism to auto-generate documentation is ready.	Will happen as part of CI/CD pipeline.	Script
3	Supporting Resources (What will be in release distribution)
3.1	Develop Catalog/Profile Content Mgt Tool		Under Development	Brian
3.2	Tooling and documentation on "how to use the converter"			Wendell
3.2.1	Point to external resources (ie Saxon HE, DOMDocument Model, etc.)			Wendell
3.2.2	Provide Instructions for running tools (ie. ReadMe.txt)			Brian
4	Web Content
4.1	Solidify Framework
4.2	Develop/Refine overarching content		See Issue #332.	Wendell (with significant help from others)
4.2.1	Concept of operations			Brian
4.2.2	Terminology list			Brian
4.2.3	Commitment statement to future compatability			Brian
4.3	Publish content to web site.			Dave (with help from others)
4.3.1	Publish Syntax Documentation (HTML files)
4.3.2	Publish production files
4.3.3	Publish Examples
4.3.4	Publish technical requirements

[david-waltermire]

4-19-19

• Based on the previous table, this issue is complete.

Follow-on work:

• Need to add an issue on completing these items to prepare for the release, and an issue for creating the release.