opensandbox-group--opensandbox/oseps/CONTRIBUTING.md

OSEP (OpenSandbox Enhancement Proposals)

Use this directory to draft, review, and store enhancement proposals before they undergo broader discussion.

Note

The OSEP process and template structure is inspired by Tekton Enhancement Proposals (TEPs).

Important

When is an OSEP required?

Use the OSEP process for changes that:

• Introduce new features or major enhancements
• Modify the core sandbox API or runtime behavior
• Affect the security model or isolation guarantees

Small bug fixes, documentation updates, and minor refactors can be submitted directly as Pull Requests without an OSEP.

Getting started

1. Run the init script to create a new proposal:

   oseps/init-osep.sh "Proposal Title"
   

   This copies the template, fills in metadata, and creates a sequentially numbered 0001-proposal-title.md draft.

2. Fill in each section from the template (Summary, Motivation, …).

3. Once ready, submit the resulting file in a PR for community review.

Available options:

oseps/init-osep.sh --help
oseps/init-osep.sh --status provisional --author "@username" "My Feature"

Template

The template used for new proposals lives at oseps/osep-template.md.template and mirrors Tekton's TEP structure while capturing the key sections needed for OpenSandbox planning. Each generated file starts with YAML front matter followed by the title and TOC:

---
title: My First Proposal
authors:
  - "@your-github-handle"
creation-date: 2025-12-21
last-updated: 2025-12-21
status: draft
---

# OSEP-0001: My First Proposal

<!-- toc -->
- [Summary](#summary)
...
<!-- /toc -->

This YAML front matter renders as a table on GitHub and keeps the proposal metadata (status, authors, dates) visible at the top of the document.

Status lifecycle

Status	Description
draft	Work in progress; not yet under formal review.
provisional	Maintainers agree with the direction; design details still pending.
implementable	Design approved and compliance checks passed; ready for implementation.
implementing	Code is being merged and SDKs are being synchronized.
implemented	Feature has reached GA status with complete documentation.
withdrawn	Author has withdrawn the proposal.
rejected	Maintainers have declined the proposal.