Merge pull request #63 from 18F/issue-61-oscal-update-docs

Update developer documentation for OSCAL model update analysis.

.gitmodules

@@ -2,9 +2,16 @@
 	path = oscal
 	url = https://github.com/usnistgov/OSCAL.git
 	branch = master
-[submodule "resources/validations/test/xspec"]
+	ignore = dirty
+
+[submodule "resources/validations/lib/xspec"]
 	path = resources/validations/lib/xspec
 	url = https://github.com/xspec/xspec.git
+	branch = master
+	ignore = dirty
+
 [submodule "resources/validations/src/schematron"]
 	path = resources/validations/lib/schematron
 	url = https://github.com/schematron/schematron.git
+	branch = master
+	ignore = dirty

resources/validations/CONTRIBUTING.md

@@ -64,4 +64,23 @@ Adding tests to the harness
 ---
 
 To add new tests, add an import to the `test-all.xpec`
-ex: `<x:import href="new_test.xspec" />`
+ex: `<x:import href="new_test.xspec" />`
+
+Analyzing Changes to OSCAL Data Models to Update Rules
+---
+
+OSCAL has abstract information models that are converted into concrete data models into XML and JSON.
+
+As a developer, you can look at individual OSCAL files that must conform to schemas for these data models, including SSPs, Components, SAPs, SARs, and POA&Ms. However, looking at individual examples for each respective model will be exhaustive and time-consuming.
+
+The schemas for the models themselves are designed and programmatically [designed, cross-referenced between JSON and XML, and generated with appropriate schema validation tools by way of the NIST Metaschema project](https://pages.nist.gov/OSCAL/documentation/schema/overview/). Therefore, it is most prudent to focus analysis on the changes in the version-controlled Metaschema declarations, as they define the abstract information model. This information model is used to generate concrete data models in JSON and XML, to be validated by JSON Schema and XSD, respectively.
+
+Developers ought to review the following relevant information sources, in order of least to most effort.
+- [Release notes from the NIST OSCAL Development Team](https://github.com/usnistgov/OSCAL/blob/master/src/release/release-notes.md), where they summarize model changes in their own words from version to version.
+- [XSLT "up-convert" transforms](https://github.com/usnistgov/OSCAL/tree/f44426e0ec14431b88833dbd381b5434d0892403/src/release/content-upgrade) give specific declarative detail on how to modify the OSCAL XML data models.
+- The source code of the Metaschema models, filtering on the release tags. Developers can use the Github web interface to compare Metaschema files, [such as this example comparison between release candidate versions `1.0.0-rc1` and `1.0.0-rc2`](https://github.com/usnistgov/OSCAL/compare/v1.0.0-rc1...v1.0.0-rc2). Focus on the files in the `src/metaschema` directory.
+
+Per [18F/fedramp-automation#61](https://github.com/18F/fedramp-automation/issues/61), programmatic diff utilities to semantically analyze the differences between OSCAL versions requires resources not available at this time.
+
+
+