Merge branch 'main' into docs/security-policy

.github/workflows/proposals.yml

@@ -0,0 +1,26 @@
+name: Validate proposals with trestle
+on:
+  pull_request:
+    branches:
+      - main
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Don't mess with line endings
+      run: |
+        git config --global core.autocrlf false
+
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+        cache: 'pip'
+
+    - name: Install trestle
+      run: pip install -r requirements.txt
+
+    - name: Run trestle validate
+      run: trestle author docs validate -tn proposals -hv

.trestle/author/proposals/0.0.1/template.md

@@ -0,0 +1,128 @@
+---
+title: yaml header here
+x-trestle-template-version: 0.0.1
+authors:
+description:
+begin-design-discussions: YYYY-MM-DD #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 
+---
+
+**Notes for users**
+This template is managed under `trestle`.
+- Do not delete or re-order the headings.
+  - When extra headings are required add them one level down from the sections you are nesting in.
+- Fill in titles and authors in the metadata
+  - Authors should be as a list of github handles.
+- When first opening a pr add the date for the  `begin-design-discussions`
+
+**Checklist**
+
+
+<!--> Add extra fields for management here <!-->
+
+- [ ] Template passes validation with `trestle`
+- [ ] Proposal cuts across multiple `oscal-compass` projects
+
+
+
+## Summary/Abstract
+
+Provide a high-level summary of the proposed change. Keep it short.
+
+This design process establishes a series of standard practices for planning and recording features or changes proposed for the project. The intent is to provide the project a consistent means to track decisions for historical reference and future plans while fully capturing how the feature or change will come to be. Additional benefits include making the process of building the release changelog easier and faster when the feature or change is ready to be released. It is a combination of a feature and effort-tracking document, a product requirements document, and a design document.
+
+## Background
+
+### Motivation and problem space
+
+Describe the need, problem, and motivation for the feature or change and any context required to understand the motivation. 
+
+### Impact and desired outcome
+
+Describe any potential impact this feature or change would have. Readers should be able to understand why the feature or change is important. Briefly describe the desired outcome if the change or feature were implemented as designed. 
+
+### Prior discussion and links
+
+Often these proposals start as an issue, forum post, email and it's helpful to link to those resources in this section to provide context and credit the right people for the idea.
+
+It is vital for projects to be able to track the chain of custody for a proposed enhancement from conception through implementation which can sometimes be difficult to do in a single Github issue, especially when it is a larger design decision or cuts across multiple areas of the project.
+
+The purpose of the design proposal processes is to reduce the amount of "siloed knowledge" in a community. By moving decisions from a smattering of mailing lists, video calls, slack messages, GitHub exchanges, and hallway conversations into a well tracked artifact, the process aims to enhance communication and discoverability.
+
+## User/User Story (Optional)
+
+Define who your the intended users of the feature or change are. Detail the things that your users will be able to do with the feature if it is implemented. Include as much detail as possible so that people can understand the "how" of the system. This can also be combined with the prior sections.
+
+## Goals
+
+List the desired goal or goals that the design is intended to achieve. These goals can be leveraged to structure and scope the design and discussions and may be reused as the "definition of done" -  the criteria you use to know the implementation of the design has succeeded in accomplishing its goals.
+
+## Non-Goals
+
+Describe what is out of scope for the design proposal. Listing non-goals helps to focus discussion and make progress.
+
+## Proposal
+
+This is where we get down to the specifics of what the proposal actually is. It should have enough detail that reviewers can understand exactly what you're proposing, but should not include things like API designs or implementation. This section should expand on the desired outcome and include details on how to measure success.
+
+## Design Details
+
+This section should contain enough information to allow the following to occur:
+* potential contributors understand how the feature or change should be implemented
+* users or operators understand how the feature of change is expected to function and interact with other components of the project
+* users or operators can take action to pre-plan any needed changes within their architecture that impacted by the upcoming feature or change if it's approved for implementation
+* decisions or opinions on a specific approach are fully discussed and explained
+* users, operators, and contributors can gain a comprehensive understanding of compatibility of the feature or change with past releases of the project.
+
+This may include API specs (though not always required), code snippets, data flow diagrams, sequence diagrams, etc. 
+
+If there's any ambiguity about HOW your proposal will be implemented, this is the place to discuss them. This can also be combined with the proposal section above. It should also address how the solution is backward compatible and how to deal with these incompatibilities, possibly with defaulting or migrations. It may be useful to refer back to the goals and non-goals to assist in articulating the "why" behind your approach.
+
+## Impacts / Key Questions
+
+List crucial impacts and key questions, some of which may still be open. They likely require discussion and are required to understand the trade-offs of the design. During the lifecycle of a design proposal, discussion on design aspects can be moved into this section. After reading through this section, it should be possible to understand any potentially negative or controversial impact of the design. It should also be possible to derive the key design questions: X vs Y.
+
+This will also help people understand the caveats to the proposal, other important details that didn't come across above, and alternatives that could be considered. It can also be a good place to talk about core concepts and how they relate. It can be helpful to explicitly list the pros and cons of each decision. Later, this information can be reused to update project documentation, guides, and Frequently Asked Questions (FAQs).
+
+### Pros
+Pros are defined as the benefits and positive aspects of the design as described. It should further reinforce how and why the design meets its goals and intended outcomes. This is a good place to check for any assumptions that have been made in the design.
+### Cons
+Cons are defined as the negative aspects or disadvantages of the design as described. This section has the potential to capture outstanding challenge areas or future improvements needed for the project and could be referenced in future PRs and issues. This is also a good place to check for any assumptions that have been made in the design.
+## 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
+
+When attempting to identify security implications of the changes, consider the following questions:
+* Does the change alter the permissions or access of users, services, components - this could be an improvement or downgrade or even just a different way of doing it?
+* Does the change alter the flow of information, events, and logs stored, processed, or transmitted?
+* Does the change increase the 'surface area' exposed - meaning, if an operator of the project or user were to go rogue or be uninformed in its operation, do they have more areas that could be manipulated unfavorably?
+* What existing security features, controls, or boundaries would be affected by this change?
+
+This section can also be combined into the one above.
+
+
+## Future Milestones (Optional)
+
+List things that the design will enable but that are out of scope for now. This can help understand the greater impact of a proposal without requiring to extend the scope of a proposal unnecessarily.
+
+## Implementation Details (Optional) 
+
+Some projects may desire to track the implementation details in the design proposal. Some sections may include:
+
+### Testing Plan
+
+An overview on the approaches used to test the implementation.
+
+### Update/Rollback Compatibility
+
+How the design impacts update compatibility and how users can test rollout and rollback.
+
+### Scalability
+
+Describe how the design scales, especially how changes API calls, resource usage, or impacts SLI/SLOs.
+
+### Implementation Phases/History
+
+Describe the development and implementation phases planned to break up the work and/or record them here as they occur. Provide enough detail so readers may track the major milestones in the lifecycle of the design proposal and correlate them with issues, PRs, and releases occurring within the project.

proposals/README.md

@@ -36,6 +36,9 @@ Complete the following steps before creating a change proposal:
 
 ## Process 
 
-* Submit a change proposal under `proposals` by opening a pull request. A proposal template with be created in the future.
+* Create an instance of the template using `trestle author docs create-sample -tn proposals`.
+* Submit a change proposal under `proposals` by opening a pull request.
+  * Ensure that the pipeline for trestle passes.
+  * This can be tested locally via `trestle author docs validate --task-name proposals -hv`
 * At least two maintainers have to approve the proposal before it can be merged.
 * Once merged, the proposal may be implemented in target project(s). The progress could be tracked using the pull request number from the merged proposal.

proposals/dogfooding-trestle-for-proposals.md

@@ -0,0 +1,136 @@
+---
+title: Dogfooding trestle for OSCAL-compass community proposals.
+x-trestle-template-version: 0.0.1
+description: "This proposal proposes using `trestle author docs` to manage the proposal documents using the CNCF design proposals template"
+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
+
+The OSCAL Compass community proposals are a structured process where there is a desire for a template to guide the process.
+
+This proposal proposes using `trestle author docs` to manage the proposal documents.
+
+## Background
+
+### Motivation and problem space
+
+As OSCAL-compass is maturing as a project there exists the need to develop more substantial processes.
+One of the processes is a design proposal process described at a [high level here](./README.md)
+There exist many templates for proposals, however, the [CNCF has a template](https://github.com/cncf/project-template/blob/main/DESIGN-PROPOSALS.md) which aligns with the communities goals.
+
+Ensuring rigour in the process can be difficult. The objective is to ensure the templates are followed for all uses.
+
+
+
+### Impact and desired outcome
+
+- Using the proposal's process itself to solidify and agree on a template and flush out issues in the pipeline.
+- Demonstrate in a practical way the use of trestle itself to the community. 
+- Enforce proposal structure and workflow.
+
+
+### Prior discussion and links
+
+- See the [PR](https://github.com/oscal-compass/community/pull/58/) for the discussion
+
+
+## User/User Story (Optional)
+
+- As a contributor to the OSCAL-compass community I would like a clear template by which to build proposals
+
+- As a reviewer of proposals I would like to know that I can easily assess whether the proposal has covered all bases.
+
+## 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
+
+- Apply to individual project issues / design goals
+- Be a stand alone demostration of trestle.
+
+## Proposal
+
+Use trestle author docs, combined with a github action pipeline, to enforce the structure of the template.
+This provides a perfect case to use `trestle` within the community generating more day-to-day user 
+feedback. 
+
+## Design Details
+
+In the case of this proposal the design and implementation are self-contained as it is self-referential.
+
+## 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
+
+- Alignment with CNCF standards.
+- Self-referential demonstration of trestle
+- Not inventing a new standard template
+
+### Cons
+
+- The CNCF template is bulky for some scenarios
+- There is overhead to new community members by using / mandating trestle.
+
+## 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. 

requirements.txt

@@ -0,0 +1 @@
+compliance-trestle>=3.3.0