This directory serves as the home for Carvel proposals. A proposal is a design document that describes a new feature for a Carvel project. The new feature can span multiple projects or introduce a new project. A proposal must be sponsored by at least one Carvel maintainer. Proposals can be worked by anyone in the community.
The Carvel proposal process is intended for "big" or complex features. If there is significant risk with a potential feature or track of work (such as complexity, cost to implement, product viability, etc.), then we recommend creating a proposal for feedback and approval. If a potential feature is well understood and doesn't impose risk, then we reccomend a standard GH issue to clarify the details.
To create a proposal, submit a PR to this directory under the appropriate
project with a terse name (for example, ytt/001-schemas/). If the proposal
concerns multiple projects or is intended for the entire Carvel suite then
please create the proposal at the root of the proposals directory (for
example, ./010-carvel-cli/).
In that directory, create a README.md containing the core proposal. Include
other files (e.g. sets of example artifacts, if necessary) to help support
understanding of the feature. When creating the proposal, please add a Status: Draft line at the top of the proposal to indicate its state.
The below template is an example. Other than the high-level details (such as title, proposal status, author, and approvers), please use whichever sections make the most sense for your proposal.
---
title: "Writing a Proposal"
authors: [ "Aaron Hurley <[email protected]>" ]
status: "draft"
approvers: [ "Cari Dean <[email protected]", "Dmitriy Kalinin <[email protected]>" ]
---
# <Proposal Title>
## Problem Statement
_This is a short summary of the problem that exists, why it needs to be
solved: what specific needs are being met. Compelling problem statements
include concrete examples (even if only by reference). How exactly the proposal
would meet those needs should be located in the "Proposal" section, not this one.
The goal of this section is to help readers quickly empathize with the target users'
current experience to motivate the proposed change.
## Terminology / Concepts
_Define any terms or concepts that are used throughout this proposal._
## Proposal
_This is the primary content of the proposal explaining how the problem(s) will
be addressed._
### Goals and Non-goals
_A short list of what the goals of this proposal are and are not._
### Specification / Use Cases
_Detailed explanation of the proposal's design._
### Other Approaches Considered
_Mention of other reasonable ways that the problem(s)
could be addressed with rationale for why they were less
desirable than the proposed approach._
## Open Questions
_A list of questions that need to be answered._
## Answered Questions
_A list of questions that have been answered._Once a proposal PR is submitted, project maintainers will review the proposal. The goal of the review is to gain an understanding of the problem being solved and the design of the proposed solution.
| Status | Definition |
|---|---|
| Draft | The proposal is actively being written by the proposer. |
| In Review | The proposal is being reviewed by project maintainers. |
| Accepted | The proposal has been accepted by the project maintainers. |
| Rejected | The proposal has been rejected by the project maintainers. |
- Author adds a proposal by creating a PR in draft mode. (Authors can save their work until ready.)
- When the author elaborates the proposal sufficiently to withstand critique they:
- change the status to
in-reviewand - mark the PR as "Ready for Review"
- change the status to
- The community critiques the proposal by adding PR reviews in order to mature/converge on the proposal.
- When the approvers reach rough consensus, they:
- change the status to
acceptedorrejected, - record both majority and dissenting opinions, and
- merge the PR.
- change the status to