feat: oscal compass project supported demos

proposals/demonstration-organisation.md

@@ -0,0 +1,157 @@
+---
+title: Management of reference demonstration repositories
+x-trestle-template-version: 0.0.1
+description: "This proposal proposes "
+authors:
+  - butler54
+begin-design-discussions: 2024-07-31 #Insert
+status: accepted #deferred, rejected, withdrawn or replaced - PR's are not accepted. Status is based on main. Rejected is unlikely to exist except where a clear record is required 
+---
+
+**Checklist**
+
+
+<!--> Add extra fields for management here <!-->
+
+- [x] Template passes validation with `trestle`
+- [x] Proposal cuts across multiple `oscal-compass` projects
+
+
+
+## Summary/Abstract
+
+OSCAL compass is built on the premise of compliance as code and gitops.
+This means that Github repositories, and organisations, are used for demonstrations including integration with CICD platforms such as github actions.
+The result is that curating this content is key.
+This proposal outlines guidelines and processes for managing demonstration content in a consistent and coherent way.
+
+## Background
+
+Over time there have been a number of demonstrations built for OSCAL compass.
+Many of these demonstrations contain overlapping functionality, however, clear ownership has not been maintained.
+Most of these demonstrations have not been reviewed at the community level, whether due to historical creation or lack of process.
+The result is we do not have a consistent set of project demonstration content.
+
+### Motivation and problem space
+
+- To improve the demonstration content itself.
+- To ensure that the primary github organization (e.g. https://github.com/oscal-compass) is a focused and clean as possible. 
+  - This will enable the 'core' to meet standards such as OpenSSF more easily
+- To ensure a minimum viable set of processes in place to manage the demo content.
+
+
+### Impact and desired outcome
+
+- Avoiding creating a dumping zone: Organizations which have 100's or 1000's of garbage projects which have been thrown into the wild.
+- W
+
+### Prior discussion and links
+
+- Mostly via slack / f2f conversations.
+
+
+## User/User Story (Optional)
+
+- As an Oscal compass contributor I have a clear process for obtaining and creating 'official' demo repositories
+- As an Oscal compass user I have a single place for clear and consistent demonstration content
+- As a potential user of Oscal compass the core organization clearly shows the projects 
+
+## Goals
+
+- Use this *inception* proposal to define a simple template
+- Enforce the use of this template by using `trestle` and a GitHub Actions pipeline
+- Extend the documentation in the [proposals README.md](./README.md) to cover the use of trestle for proposals
+- Minimize the authors effort by using GitHub metadata where appropriate.
+
+## Non-Goals
+
+- Demonstrations are not the default for regression tests. Testing should be part of the main project.
+- To decide what are the priority demonstrations for oscal-compass
+
+## Proposal
+
+1. Reference demonstrations are not included in the [`oscal-compass`](https://github.com/oscal-compass) organization. Demonstrations are confined the `oscal-compass-demos` organization.
+2. Due to the nature of Oscal-compass, demonstrations are likely to span multiple repositories. Each demonstration should at least have a descriptive name which is the root repository of the demonstration that includes documentation: 
+   - `https://github.com/oscal-compass-demos/acme-corp-cloud` # An oscal compass demo for 'ACME corps' cloud
+   - `https://github.com/oscal-compass-demos/trestle-markdown-rendering` # An oscal compass demo repository for markdown rendering
+3. Repository should avoid names which are not readily readable or use unnecessary acronyms , shortened, or not contextualized
+   - `https://github.com/oscal-compass-demos/e2e` # Not specific
+   - `https://github.com/oscal-compass-demos/ISM` # Bad not everyone knows was the Australian ISM IS
+   - `https://github.com/oscal-compass-demos/AUGOVISM` # Hard to decipher / search
+   - `https://github.com/oscal-compass-demos/Australian-govt-ISM` # provides sufficient context.
+   - `https://github.com/oscal-compass-demos/kubecon-japan-2025` # detailed for an event. 
+4. Secondary repositories begin with the name of the demonstration
+   - e.g `https://github.com/oscal-compass-demos/acme-corp-cloud-catalog`
+
+5. Demonstration content MUST be stable. 
+   - E.g. Owners MUST NOT update the repos under `https://github.com/oscal-compass-demos` in order to run the demo, the demonstration SHOULD be forked.
+6. Demonstration repositories can be nominated via an issue in the  [`community`](https://github.com/oscal-compass/community)
+   1. Demonstrations MUST have at two maintainers nominated.
+   2. The name of the demonstration; a description of the intent of the demonstrations; and the repositories are required
+7. Demonstrations MUST be actively maintained to the currently supported versions of `oscal-compass`
+8. Demonstrations that are not maintained will either be:
+   1. Archived, or
+   2. Actively document to user why there are limits (e.g. relies on 3rd party content that leverages an old version of OSCAL).
+9.  Demonstrations must include appropriate blerbs and cross linking from:
+   1.  Oscal Compass community website
+   2.  and optionally project websites (e.g. `compliance-trestle` or `compliance-to-policy`)
+
+
+## Design Details
+
+Sufficient details are above.
+
+## Impacts / Key Questions
+
+The proposal is relatively simple.
+
+The biggest question is how much needs to be recorded in the document itself as opposed to being extracted from the history on GitHub (such as approvers).
+
+
+### Pros
+
+
+### Cons
+
+TBC BELOW THIS POINT
+
+## Risks and Mitigations
+
+Describe the risks of this proposal and how they can be mitigated. This should be broadly scoped and describe how it will impact the larger ecosystem and potentially adopters of the project; such as if adopters need to immediately update, or support a new port or protocol. It should include drawbacks to the proposed solution. 
+
+### Security Considerations
+
+This proposal relies on the underlying configuration of the underlying GitHub project to maintain security of the process.
+
+The process is not intended for security-related processes such as responsible disclosure.
+
+
+## Future Milestones (Optional)
+
+None
+
+## Implementation Details (Optional) 
+
+In addition to this pull request:
+
+1. GitHub actions will need to be configured.
+2. GitHub project configuration should ensure the required reviewers and actions pipelines are required.
+
+
+### Testing Plan
+
+Post implementation the first proposal which is not authored by this PR's should examine the workflow.
+
+
+### Update/Rollback Compatibility
+
+None - this is the starting point.
+
+### Scalability
+
+No concerns
+
+### Implementation Phases/History
+
+This is self contained to this PR and is net new capability.
+Lifecycle management can be conducted using the ability of `trestle author docs` to support multiple template revisions.