Skip to content

Commit 7a2fa84

Browse files
[DOCUMENTATION] Draft for AI Usage Policy (- WIP #367 -)
Additions with file .github/AI_USAGE_POLICY.md: * Documentaed initial draft of AI policy to communicate impact on project
1 parent e4b9bc9 commit 7a2fa84

File tree

1 file changed

+144
-0
lines changed

1 file changed

+144
-0
lines changed

.github/AI_USAGE_POLICY.md

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Multicast Project AI Usage Policy
2+
3+
## 1. Purpose and Scope
4+
5+
This policy governs the use of AI tools, particularly CodeRabbitAI, GH Copilot, and Codecov-ai-reviewer, within the Multicast project's development workflow. It establishes guidelines for responsible AI integration while maintaining the project's security, quality, and integrity.
6+
7+
## 2. AI Role Definitions
8+
9+
### 2.1 Permitted AI Roles :information_desk_person:
10+
11+
* 2.1.A Assistive Code Review:
12+
* AI may provide feedback on code quality, style compliance, and potential issues
13+
* 2.1.B Assistive Project-Management Delegation:
14+
* AI may provide feedback when requested on GHI (GitHub issues), as well as open new, or comment on existing, GHI, to track suggested improvements to the project content.
15+
* 2.1.C Documentation Improvement:
16+
* AI may suggest improvements to documentation clarity and completeness
17+
* 2.1.D Test Coverage Analysis:
18+
* AI may identify areas lacking test coverage
19+
Code Generation Assistance: AI may suggest code implementations when requested
20+
21+
> [!CAUTION]
22+
> However, AI may **NOT** apply changes, nor code suggestions, by themselves, to any protected branch (That is reserved for qualified human contributors).
23+
24+
### 2.2 Prohibited AI Roles :no_entry_sign:
25+
26+
* 2.2.A Sole Developer:
27+
* AI (especially LLM type AI) is not well suited for innovation; No vibe-coding, the direction and development of the project CAN-NOT meaningfully come from AI.
28+
* 2.2.B Sole Approver:
29+
* AI approval alone is insufficient for merging any PR.
30+
31+
> [!WARNING]
32+
> Only project admin may sufficiently act as a Sole Approver, and _even_ that is discouraged.
33+
* 2.2.C Security Gatekeeper:
34+
* AI cannot be the only mechanism for security validation
35+
* 2.2.D Unrestricted Auto-Merge:
36+
* AI cannot trigger auto-merge without human verification
37+
38+
## 3. PR Review Process
39+
40+
### 3.1 Required Human Review
41+
42+
* 3.1.A Human Review
43+
* All PRs MUST receive at least one human review from an authorized maintainer
44+
* 3.1.B Verify or Resolve
45+
* Human reviews must verify (or conversely reject) the AI's suggestions.
46+
* Discussions are encouraged in both cases, as Humans and AI alike, may later consider relevant project content in future reviews.
47+
* 3.1.C Very Large PRs
48+
* For PRs exceeding 99 changed files, at least two human reviews are recommended.
49+
> [!NOTE]
50+
> Currently there is only one core maintainer. Hoping to change this.
51+
52+
* 3.1.D Review Conventions and Instructions
53+
* The project's code review conventions are currently enumerated in the living document: [CEP-4](https://gist.github.com/reactive-firewall/cc041f10aad1d43a5ef15f50a6bbd5a5) (convention enhancement proposal no.4)
54+
55+
## 3.2 AI Review Requirements
56+
57+
### 3.2 AI Assisted Code Review
58+
59+
* 3.2.A AI Review Purpose
60+
* AI reviews are supplementary and do not replace human review
61+
* 3.2.B AI Troubleshooting
62+
* When AI review is triggered but fails (e.g., due to throttling), the PR must be marked as requiring additional attention
63+
* AI approval comments should not be used to bypass branch protection rules
64+
65+
### 3.3 Large PR Handling
66+
67+
* 3.3.A Less is More
68+
* PRs with more than 100 changed files should be split into smaller PRs when possible
69+
When splitting is not feasible, PR authors must provide a summary highlighting the most critical changes for human reviewers
70+
71+
## 4. Security Considerations
72+
73+
### 4.1 Verification and Validation
74+
75+
* 4.1.A Review Line-by-Line
76+
* Absolutely, NO "Vibe-coding" is acceptable for this project. ALL AI-suggestions MUST be understood by at least one core maintainer (same as all other reviewed code needs to be)
77+
> [!TIP]
78+
> > Good code is its own best documentation. As you're about to add a comment, ask yourself, "How can I improve the code so that this comment isn't needed?" Improve the code and then document it to make it even clearer.
79+
> - Steve McConnell
80+
81+
* All AI-suggested code changes must be verified by a human maintainer (see 3.1.B).
82+
* 4.1.B Signed Commits
83+
* Code signing with different keys for human vs. AI contributions is required.
84+
* 4.1.C Security Assessments
85+
* AI-suggested security fixes must undergo additional human security review.
86+
87+
### 4.2 Branch Protection
88+
89+
* 4.2.A Stable and master branches must maintain protection rules requiring:
90+
* Minimum of one human approval
91+
* Signed commits
92+
* Passing CI checks
93+
* Force-pushing to protected branches is prohibited
94+
95+
### 4.3 CWE-655 Mitigation
96+
97+
* 4.3.A dual-approval system
98+
* The project implements a dual-approval system to help prevent single points of failure.
99+
* AI approvals are tracked separately from human approvals in the review process. Humans
100+
must be responsible for the actual merge of pull-requests.
101+
* Every user (eg. AI, or human) must have a distinct code-signing identity (see 4.1.B).
102+
* Only human controlled identities may merge branches, or commit to the default branch directly.
103+
104+
## 5. Implementation and Compliance
105+
106+
### 5.1 Configuration Management
107+
108+
* 5.1.A CoderabbitAI Configuration
109+
* The `.coderabbit.yaml` file is the source of truth for CodeRabbitAI configuration.
110+
* 5.1.B Dependabot Configuration
111+
* The `.github/dependabot.yml` file is the source of truth for @dependabot configuration.
112+
* 5.1.C Changes
113+
* Changes to these configurations require PR approval from at least one core maintainer.
114+
* 5.1.D Audits
115+
* Regular audits of AI configuration will be conducted to ensure alignment with this policy.
116+
117+
### 5.2 Monitoring and Reporting
118+
119+
* 5.2.A Monitoring
120+
* Periodic audits of PR approvals will verify compliance with this policy
121+
* 5.2.B Reporting
122+
* Security incidents related to AI usage must be reported via project security channels
123+
124+
### 5.3 Developer Training
125+
126+
* 5.3.A Contributors should understand the limitations of AI tools in the review process
127+
* 5.3.B Clear communication about when and how to utilize AI assistance will be provided
128+
* 5.3.C New contributors will be directed to this policy as part of onboarding
129+
130+
## 6. Exceptions
131+
132+
## 6.1 Exceptions to this policy require:
133+
134+
* 6.1.A Documented justification
135+
* 6.1.B Approval from at least two core maintainers
136+
* 6.1.C Time-limited scope with defined expiration
137+
* 6.1.D Post-implementation security review
138+
139+
## 7. Policy Review
140+
141+
### 7.1 This policy will be reviewed:
142+
143+
* 7.1.A After any security incident involving AI tools
144+
* 7.1.B When significant changes to project AI integration are proposed

0 commit comments

Comments
 (0)