/ GOVERNANCE.md
GOVERNANCE.md
1 # OpenSandbox Governance 2 3 This document describes how OpenSandbox is governed today and how technical 4 decisions are made in the project. 5 6 It is intended to reflect the project's current open development practice. As 7 OpenSandbox grows, this document may evolve to support a more formal governance 8 model. 9 10 ## Goals 11 12 OpenSandbox governance is designed to keep the project: 13 14 - open to contributors and users 15 - pragmatic in day-to-day decision making 16 - transparent in technical direction 17 - safe for public API, runtime, and security-sensitive changes 18 - sustainable across multiple components and maintainers 19 20 ## Scope 21 22 This document applies to the OpenSandbox repository and its major public 23 surfaces, including: 24 25 - public APIs and specifications in `specs/` 26 - the lifecycle server in `server/` 27 - runtime components in `components/` 28 - Kubernetes controller and related assets in `kubernetes/` 29 - SDKs in `sdks/` 30 - CLI, examples, and project documentation 31 32 ## Project Values 33 34 OpenSandbox maintainers and contributors are expected to act consistently with 35 these principles: 36 37 - **Open development**: design discussion, issue tracking, and code review 38 happen in public whenever possible. 39 - **Compatibility awareness**: public APIs, SDKs, CLI behavior, and documented 40 user workflows should not change casually. 41 - **Security first**: changes affecting isolation, networking, credentials, or 42 execution safety require extra scrutiny. 43 - **Component ownership with cross-project accountability**: subsystem 44 maintainers own their areas, while cross-cutting changes require broader 45 review. 46 - **Documentation and implementation alignment**: public contracts, code, SDKs, 47 examples, and docs should stay consistent. 48 49 ## Roles 50 51 ### Contributors 52 53 Contributors are anyone who participates in the project, including by: 54 55 - opening issues or discussions 56 - submitting pull requests 57 - reviewing code 58 - improving docs, tests, examples, or tooling 59 60 Contributors are expected to follow: 61 62 - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 63 - [CONTRIBUTING.md](CONTRIBUTING.md) 64 - [SECURITY.md](SECURITY.md) for vulnerability reporting 65 66 ### Maintainers 67 68 Maintainers are contributors entrusted with reviewing and guiding changes in one 69 or more parts of the repository. 70 71 Today, the public record of subsystem maintainership is the 72 [`CODEOWNERS`](.github/CODEOWNERS) file. Code owners for a given path are the 73 default maintainers for that area. 74 75 Maintainer responsibilities include: 76 77 - reviewing pull requests for owned areas 78 - helping preserve code quality, compatibility, and security 79 - requesting cross-component review when a change affects other surfaces 80 - keeping specs, implementation, tests, docs, and examples aligned when needed 81 - helping contributors land changes successfully 82 83 ### Project Maintainers 84 85 Project Maintainers are the maintainers responsible for repository-wide 86 direction and final technical decisions when a matter cannot be resolved within 87 normal component review. 88 89 Until a dedicated `MAINTAINERS.md` is added, the fallback `*` owners in 90 [`CODEOWNERS`](.github/CODEOWNERS) are treated as the public list of current 91 Project Maintainers. 92 93 Project Maintainers are responsible for: 94 95 - cross-cutting technical decisions 96 - governance updates 97 - maintainer onboarding and offboarding 98 - resolving review deadlocks 99 - ensuring major changes follow the appropriate design process 100 101 ## Decision Making 102 103 ### Day-to-Day Changes 104 105 Most changes are made through the normal pull request workflow described in 106 [CONTRIBUTING.md](CONTRIBUTING.md): 107 108 1. discuss the change in an issue when appropriate 109 2. submit a pull request 110 3. pass automated checks 111 4. receive maintainer review for affected areas 112 5. address feedback 113 6. merge once approved 114 115 Normal changes are decided by maintainer review and rough consensus. 116 117 ### Component-Level Decisions 118 119 For changes limited to one subsystem, the maintainers of that subsystem are the 120 primary decision makers. Their review should carry the most weight for: 121 122 - implementation details 123 - code structure 124 - tests 125 - operational behavior within that component 126 127 If a change affects multiple subsystems, the relevant maintainers should be 128 involved before merge. 129 130 ### Cross-Cutting and Sensitive Decisions 131 132 Changes with broader impact require wider review. This includes changes to: 133 134 - public APIs or schemas in `specs/` 135 - SDK interfaces or generated outputs 136 - CLI behavior 137 - lifecycle semantics 138 - runtime isolation or security guarantees 139 - ingress, egress, or authentication behavior 140 - release processes or repository-wide tooling 141 142 For these changes, maintainers should seek explicit review from all materially 143 affected areas, not just the first area touched by the patch. 144 145 ### Major Design Changes and OSEPs 146 147 OpenSandbox uses the OpenSandbox Enhancement Proposal process (`OSEP`) for major 148 changes. 149 150 An OSEP is expected for changes that: 151 152 - introduce major features or architectural changes 153 - modify the core API or runtime behavior 154 - affect the security model or isolation guarantees 155 156 The public OSEP process is documented in: 157 158 - [oseps/README.md](oseps/README.md) 159 - [oseps/CONTRIBUTING.md](oseps/CONTRIBUTING.md) 160 161 When an OSEP is required, implementation should follow the approved design 162 direction rather than bypassing it through code review alone. 163 164 ### Consensus and Voting 165 166 OpenSandbox prefers **lazy consensus** for most technical decisions: 167 168 - if affected maintainers agree, the change may proceed 169 - if concerns are raised, they should be addressed in the PR, issue, or OSEP 170 discussion 171 172 If consensus cannot be reached in a reasonable time, Project Maintainers may use 173 a simple majority vote of participating Project Maintainers. 174 175 Voting rules: 176 177 - each participating Project Maintainer has one vote 178 - maintainers should recuse themselves in case of direct conflicts of interest 179 - if a vote ties, the proposal does not pass and the status quo remains 180 181 ## Reviews and Merge Expectations 182 183 The following expectations apply before merge: 184 185 - relevant CI checks should pass, or failures must be understood and accepted by 186 maintainers 187 - at least one maintainer of the affected area should review the change 188 - cross-cutting changes should be reviewed by all materially affected areas when 189 practical 190 - breaking changes should be clearly called out, with migration guidance where 191 needed 192 - docs and tests should be updated when behavior changes 193 194 Maintainers may decline or defer a change if it: 195 196 - conflicts with approved design direction 197 - introduces unnecessary compatibility risk 198 - weakens security or isolation without a strong justification 199 - mixes unrelated work into a single change 200 201 ## Public Interfaces and Compatibility 202 203 OpenSandbox treats several surfaces as public contracts: 204 205 - API specifications in `specs/` 206 - published SDKs 207 - CLI behavior 208 - documented configuration and deployment behavior 209 210 Maintainers should prefer additive and backward-compatible changes when 211 possible. 212 213 When changing a public contract, maintainers should update or verify the 214 affected implementation, SDKs, docs, examples, and release outputs in the same 215 change when practical. 216 217 ## Releases 218 219 Releases are managed through the public workflows and scripts in this 220 repository, including the GitHub Actions workflows under `.github/workflows/` 221 and the release tooling documented in `docs/release-automation.md`. 222 223 Maintainers responsible for a release target are expected to ensure that: 224 225 - the target has appropriate validation 226 - release notes accurately reflect user-visible changes 227 - versioning and tags follow the documented release conventions 228 229 ## Communication Channels 230 231 The project's public collaboration channels are: 232 233 - GitHub Issues for bugs, feature requests, and implementation questions 234 - GitHub Discussions for broader design discussion and community help 235 - pull requests for concrete code and documentation review 236 - OSEPs for major design work 237 238 Security issues should follow the private reporting guidance in 239 [SECURITY.md](SECURITY.md). 240 241 ## Becoming a Maintainer 242 243 New maintainers are selected based on sustained, high-quality contribution to 244 the project. 245 246 Signals that someone may be ready for maintainership include: 247 248 - repeated high-quality code or documentation contributions 249 - strong reviews and constructive technical feedback 250 - reliable follow-through on owned work 251 - good judgment on compatibility, security, and project direction 252 - collaborative behavior with contributors and maintainers 253 254 The typical process is: 255 256 1. nomination by an existing Project Maintainer 257 2. discussion among Project Maintainers 258 3. no unresolved objections after a reasonable review period, or approval by 259 majority vote if needed 260 4. update of `CODEOWNERS` and any other relevant public maintainer records 261 262 ## Maintainer Inactivity and Removal 263 264 Maintainers may step down at any time by notifying the project. 265 266 Project Maintainers may also update maintainer status when someone has been 267 inactive for an extended period, for example several months without meaningful 268 review or maintenance activity. 269 270 Removal should be handled respectfully and pragmatically, with the goal of 271 keeping ownership accurate rather than punitive. 272 273 Maintainers may also be removed for serious violations of project expectations, 274 including repeated abuse of project privileges or violations of the Code of 275 Conduct. 276 277 ## Governance Changes 278 279 Changes to this document should be made through a public pull request. 280 281 Governance changes should receive review from Project Maintainers and should not 282 be merged without giving maintainers and contributors a reasonable opportunity 283 to comment. 284 285 Substantial governance changes may be proposed through an OSEP or a dedicated 286 governance discussion if maintainers believe broader review is warranted.