beps/README.md
A Backstage Enhancement Proposal (BEP) is a way to propose, communicate and coordinate on new efforts for the Backstage project.
beps/NNNN-short-descriptive-title, where NNNN is the next available number padded with leading zeroes.The merging of a BEP means that it is approved for implementation and has an owner that is responsible for said implementation. Up until that point, the author(s) of the BEP are responsible for driving the BEP forward.
While the BEP PR is open the owner can open separate PRs to ship experimental features in support of the BEP to help drive the design forward, and these may be merged pending usual PR review. If the BEP is withdrawn or rejected these features should generally be removed.
No, but it is recommended for larger changes and contributions that affect the Backstage framework or core features where you want to make design decisions upfront and iterate on them across several PRs.
An RFC issue is a good way to receive feedback on an idea. The BEP process may involve getting feedback on an idea, but it takes things further by making it easier to iterate on the design of a new feature, getting it approved by the owning project area maintainers, and tracking its implementation.
While anyone can open an RFC issue, the features added by a BEP need to be approved by the owners before it can be merged. The BEP will also contain the latest agreed upon design, whereas an RFC issue is more of a discussion forum.
Often a BEP can start out as an RFC issue, which may then be converted into a BEP once the idea has received an owner and been approved.
No, except for plugins that implement core features of Backstage. The BEP process is only intended for changes to the Backstage framework and core features.
Yes! As long as the BEP is in the implementable state. Updates should however only be done based on new discoveries during the implementation phase. If you want to make a significant change to a BEP that has already been approved, you should open a new BEP to replace the old one.
Yes! BEPs are living documents and anyone can suggest changes to them. We encourage to challenge the design decisions in a BEP and suggest alternatives. You can also help fill out details in a BEP that has not yet been fully fleshed out.
Architecture Decision Records (ADRs) are used to document decisions made for development within the Backstage project. They are not intended to be used for proposing new features or changes to Backstage.
This is a state from an older version of the BEP process, and means that it has been approved as work to be done but the exact design is not yet agreed upon. BEPs in this state need to be moved to the implementable state before they can be implemented.
The BEP process is still evolving!
If something is missing or not answered here feel free to reach out on our community Discord. If you want to propose a change to the BEP process you can also open a PR directly with your proposal.
At the start of each BEP is a YAML document that contains metadata about the BEP. These are the fields that should currently be provided:
| Field | Description |
|---|---|
| title | The title of the BEP in plain language. The title will also be used in the BEP filename. See the template for instructions and details. |
| status | The current state of the BEP, must be one of the values listed in the BEP Status section. |
| authors | A list of GitHub IDs for the authors of the BEP. Typically only the original authors are included, but additional authors can be added if significant contributions are made. |
| owners | A list of GitHub IDs for the owners of the BEP. The owners are responsible for the implementation of the BEP, and are required for the BEP to move to the implementable status. |
| project-areas | The Project Areas closely associated with this BEP that need to approve it. For a list of existing project areas, see OWNERS.md. If the BEP is not related to any existing project area, use core-maintainers instead. |
| creation-date | The yyyy-mm-dd date that the BEP was first submitted in a PR. |
The BEP Status is critical to clearly communicate the status of each BEP. Each BEP must have its status field set to one of the following values:
implementable: The BEP has been approved for implementation by the owning project area maintainers.implemented: The BEP has been implemented.deferred: The BEP was approved but is no longer being actively worked on. If anyone wishes to pick up the work they can move it back to the implementable state.rejected: The approvers and authors have decided that this BEP is not moving forward. The BEP is kept around as a historical document.replaced: The BEP has been replaced by a new BEP.The BEP process is heavily inspired by the Kubernetes Enhancement Proposal (KEP) process.