diff --git a/proposals/demonstration-organisation.md b/proposals/demonstration-organisation.md new file mode 100644 index 0000000..1817812 --- /dev/null +++ b/proposals/demonstration-organisation.md @@ -0,0 +1,163 @@ +--- +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`) +10. Event specific demonstrations (e.g. Kubecon) should follow the following practice + 1. The SHOULD be kept stable with respect to the documentation and videos + 2. If reused in another event they MUST be renamed with another project name + 3. If reused and renamed the events it is used at MUST be referenced in the README.md for traceability + + +## 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 +- Provides clear guidance to curate demonstrations +- Keeps the core organisation clear +- Provides clear expectations for both demo developers and consumers. +- Provides expectations to demo developers and maintainers of required ongoing efforts. + +### Cons + +- It's additional overhead from an OSCAL compass organization perspective which carries the risk of being ignored. + + +## Risks and Mitigations + +N/A + +### Security Considerations + +- Github Actions automation carries risks based on how authorization is performed. This proposal will decrease risk as it isolates demo automation further away from core oscal compass projects. + +- The ongoing risk with authoritative demonstrations is that it is a larger body of code and projects +## Future Milestones (Optional) + +None + +## Implementation Details (Optional) + +1. Setup the organization via the CNCF with the correct set of permissions. +2. Create a request workflow for new demo repos in the community github organization. +3. (Optional) create a minimum GitHub template, in the demo to provide organizational minimums. + 1. CNCF references and licenses + 2. Minimum Security workflows for actions + 3. Any other standards deemed necessary +4. Identify and move across existing projects. + +### Testing Plan + +None + +### Update/Rollback Compatibility + +The biggest issue is the movement of projects from a URL perspective. Thankfully most of these issues are managed by Github. + +### Scalability + +No concerns + +### Implementation Phases/History + +The biggest implementation challenge is (4) above. This will need to be conducted in phases. \ No newline at end of file