The Coalition for Secure AI (CoSAI) is an open-source project that is actively seeking contributions from any willing participants. Here are some guidelines for people that would like to contribute to the project.
In general, a CoSAI Contributor is expected to:
- be knowledgeable in one or more fields related to the project
- contribute to the developing and finalizing the workstream deliverables
- be reliable in completing issues to which they have been assigned
- show commitment over time with one or more PRs merged
- follow the project style and testing guidelines
- follow branch, PR, and code style conventions
- contribute in ways that substantially improve the quality of the project and the experience of people who use it
When contributing to any CoSAI repository, please first discuss the change you wish to make via a Github Issue, or in an email to the specific Workstream mailing list.
Please note this project follows the OASIS Participants Code of Conduct; please be respectful of differing opinions when discussing potential contributions.
CoSAI uses a two-stage governance process for content updates to our risk, control, and component framework. This process separates technical review from community governance, ensuring both code quality and community alignment.
Content updates include changes to:
- Risk framework definitions and categories
- Security control specifications and mappings
- Component framework elements and relationships
- Framework documentation and guidance materials
Stage 1: Technical Review - Content feature branches merge to the develop branch after standard PR review
Stage 2: Community Review - Bi-weekly CoSAI governance review of the develop branch's accumulated changes
feature-branch → develop → main
↑ ↑ ↑
Stage 1 Stage 2 Release
(Technical) (Community)
The following types of changes are not covered by the two-stage content update process and continue to follow existing workflows:
- Bug fixes - Technical corrections and error resolution
- Implementation changes - Updates to code logic, algorithms, or system functionality
- Infrastructure updates - CI/CD, build processes, deployment configurations
- Documentation fixes - Corrections to technical documentation, README updates, etc.
- Security patches - Critical security-related fixes requiring immediate deployment
- Dependency updates - Library upgrades, security patches for dependencies
These excluded change types may follow direct-to-main workflows as determined by existing repository policies.
If you are new to the CoSAI project and are looking for an entry-point to make your first contribution, look at the open issues. Issues that are tagged with good first issues are meant to be small pieces of work that a first-time contributor can pick-up and complete. If you find one that you'd like to work on, please assign yourself or comment on the issue and one of the maintainers can assign it for you.
If you want to create a new issue that doesn't exist already, just open a new one.
This repository provides structured GitHub issue templates to streamline content proposals:
- Issue Templates Guide - Complete guide for all 9 issue templates
- Control templates (new/update)
- Risk templates (new/update)
- Component templates (new/update)
- Persona templates (new/update)
- Infrastructure template
The templates capture required information, reduce clarification cycles, and maintain consistency across proposals. They include automatic bidirectional mapping support, reference documentation links, and clear examples.
For framework content changes (controls, risks, components, personas), please use the appropriate issue template to ensure all necessary details are captured.
The process for submitting pull requests depends on the type of change:
Follow these steps when submitting content updates:
- Fork this repo into your GitHub account. Read more about forking a repo on Github here.
- Create a new branch, based on the
developbranch, with a name that concisely describes what you're working on. - Ensure that your changes do not cause any existing tests to fail.
- Submit a pull request against the
developbranch.
Stage 1 Review: Your PR to develop will be reviewed for technical criteria including code hygiene, formatting standards, commit message quality, and technical implementation correctness.
Stage 2 Review: Every 2 weeks, a PR will be created from develop to main containing all merged feature changes from the cycle period. This undergoes CoSAI community review using established consensus and voting procedures.
Follow these steps when submitting non-content changes (bug fixes, implementation changes, infrastructure updates, etc.):
- Fork this repo into your GitHub account.
- Create a new branch, based on the
mainbranch, with a name that concisely describes what you're working on. - Ensure that your changes do not cause any existing tests to fail.
- Submit a pull request against the
mainbranch.
- PR will be reviewed by the maintainers and approved by workstream leads or their delegates (maintainers)
- Responses are due in 3 business days
The workstream maintainers are responsible for reviewing pull requests and issues in a timely manner (3 business days).
Lazy consensus is practiced for all projects and documents, including the main project repository and draft documents using other tools than Github.
Major changes on Github or to a WS document using any other official project platform should be accompanied by a post on the WS mailing list as appropriate. Author(s) of the proposal, Pull Requests, or issues, will give a time period of no less than seven (7) business days for comment and remain cognizant of popular observed world holidays.
main– main development branch and authoritative source; updated only after community approval for content changesdevelop- staging area for community review of content updates; feature branches for content changes target this branchfeature– feature/this-is-a-new-feature-branch (targetdevelopfor content updates,mainfor non-content changes)codebugfix– codebugfix/name-of-the-bug (typically targetsmain)languagefix- languagefix/fix-details (typically targetsmain)release– release/1.0.0 - cut from main when ready
For content updates: After completing work on a feature branch, rebase develop before opening a PR. After PR is approved, rebase again to make sure changes from the latest develop are picked up before merging the PR.
For non-content changes: After completing work on a feature branch, rebase main before opening a PR. After PR is approved, rebase again to make sure changes from the latest main are picked up before merging the PR.
In the commit message, always continue the sentence "This commit does ...".
Examples of good commit messages: "This commit renames examples folder in the root of the repo to reference-implementations" "This commit bumps dependency packages versions to fix potential security issues".
Anyone can do a pull request and commit. In order for your work to be merged, you will need to sign the iCLA (individual contributor agreement) if you are just contributing for yourself. If you are contributing on behalf of your company, you will also need to to sign the eCLA (entity contributor agreement). Learn more about the CLAs here.
The iCLA is administered by a bot which will comment on your PR and direct you to sign the iCLA if you haven't previously done so. This happens automatically when people submit a pull request.
If you are contributing to the CoSAI Risk Map (schemas and YAML under risk-map/), follow this document for branching, commits, PRs, and CLA.
- Risk Map authoring guide (schemas/YAML, IDs, validation, examples): see
risk-map/docs/developing.md.
Questions or comments about this project's work may be composed as GitHub issues or comments or may be directed to the project's general email list at cosai-op@lists.oasis-open-projects.org. General questions about OASIS Open Projects may be directed to OASIS staff at op-admin@lists.oasis-open-projects.org.