Skip to content

developing.md

Latest commit

 

History

History
113 lines (78 loc) · 4.08 KB

developing.md

File metadata and controls

113 lines (78 loc) · 4.08 KB

Expanding the CoSAI Risk Map

This guide complements the repository-wide CONTRIBUTING.md. Use that for branching, commit/PR workflow, code review expectations, and CLA. This document focuses on how to author and validate Risk Map content (schemas and YAML).

Note: all contributions discussed in this document would fall under the Content Update Process covered in detail in the CONTRIBUTING.md document

This guide outlines how you can contribute to the Coalition for Secure AI (CoSAI) Risk Map. By following these steps, you can help expand the framework while ensuring your contributions are consistent with the project's structure and pass all validation checks.

Documentation Index

Getting Started

Setup & Prerequisites

  • Installing dependencies and pre-commit hooks
  • Setting up Python, Node.js, and validation tools
  • Platform-specific configuration for SVG generation

Development Tools

Validation Tools

  • Manual edge validation and graph generation
  • Markdown table documentation
  • Control-to-risk reference validation
  • Prettier formatting and Ruff linting
  • Command reference for all validation tools

Graph Customization

  • Customizing Mermaid graph appearance
  • Foundation design tokens and color schemes
  • Graph layout and spacing configuration
  • Testing and visualizing customizations
  • Common customization examples

CI/CD Validation

  • GitHub Actions automated validation
  • Graph validation in pull requests
  • SVG generation from Mermaid diagrams
  • Handling CI validation failures

Frontend Test Conventions

  • Conventions for node --test ES-module tests under site/tests/
  • Scope, fixtures, concurrency, and escalation path for DOM or framework changes

Contributing Content

General Contribution Workflow

  • Overall process for contributing content
  • Using validation tools during development
  • Creating pull requests

Issue Templates Guide

  • Using GitHub issue templates to propose new content or updates
  • Complete guide for all 9 available templates
  • Examples, required fields, and automatic bidirectionality
  • Framework applicability and schema evolution guidance

Template Sync Procedures (For Maintainers)

  • How templates stay synchronized with schemas
  • Manual synchronization procedures
  • Two-week sync lag explanation
  • Automation roadmap and troubleshooting

Content Addition Guides:

Reference

Troubleshooting

  • Edge validation errors
  • Graph generation issues
  • Common problems and solutions

Best Practices

  • Development workflow recommendations
  • Validation strategies
  • Documentation standards
  • Graph preview techniques

Writing Documentation

  • How to write testable Python code examples
  • Skip markers for documentation-only code
  • Working directory and file path guidelines
  • Testing examples locally

Quick Links

  • Repository CONTRIBUTING.md - Branch strategy, PR workflow, CLA
  • Scripts Documentation - Git hooks and validation scripts
  • Component Schema: risk-map/schemas/components.schema.json
  • Controls Schema: risk-map/schemas/controls.schema.json
  • Risks Schema: risk-map/schemas/risks.schema.json
  • Personas Schema: risk-map/schemas/personas.schema.json
  • Frameworks Schema: risk-map/schemas/frameworks.schema.json