mirror of
https://github.com/katanemo/plano.git
synced 2026-05-06 14:22:51 +02:00
update roadmap
This commit is contained in:
adilhafeez
parent
978b1ea722
commit
1d0296f1ce
3 changed files with 423 additions and 0 deletions
142
docs/peps/PEP-0000-process.md
Normal file
142
docs/peps/PEP-0000-process.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
# PEP-0000: Plano Enhancement Proposal Process
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **PEP** | 0000 |
|
||||
| **Title** | Plano Enhancement Proposal Process |
|
||||
| **Status** | Active |
|
||||
| **Authors** | Plano Maintainers |
|
||||
| **Created** | 2026-04-07 |
|
||||
|
||||
## What is a PEP?
|
||||
|
||||
A **Plano Enhancement Proposal (PEP)** is a design document that describes a significant change to the Plano project. PEPs provide a structured way to propose, discuss, and track major features, architectural changes, and process improvements.
|
||||
|
||||
PEPs are inspired by [Kafka's KIP process](https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals), [Kubernetes KEPs](https://github.com/kubernetes/enhancements/tree/master/keps), and [Envoy's design document process](https://github.com/envoyproxy/envoy/blob/main/CONTRIBUTING.md).
|
||||
|
||||
## When is a PEP Required?
|
||||
|
||||
A PEP is required for changes that:
|
||||
|
||||
- Introduce a new user-facing feature or capability
|
||||
- Change existing user-facing behavior in a breaking way
|
||||
- Add a new subsystem or architectural component
|
||||
- Modify the configuration schema in a significant way
|
||||
- Add a new LLM provider with non-standard API patterns
|
||||
- Change the project's processes or governance
|
||||
|
||||
A PEP is **not** required for:
|
||||
|
||||
- Bug fixes
|
||||
- Documentation improvements
|
||||
- Refactoring that doesn't change behavior
|
||||
- Adding models to an existing provider
|
||||
- Minor CLI improvements
|
||||
- Test improvements
|
||||
- Dependency updates
|
||||
|
||||
When in doubt, open a GitHub issue or Discussion first. A maintainer will let you know if a PEP is warranted.
|
||||
|
||||
## PEP Lifecycle
|
||||
|
||||
```
|
||||
Draft → Under Review → Accepted → Implementing → Complete
|
||||
↘ Declined
|
||||
↘ Deferred
|
||||
↘ Withdrawn
|
||||
```
|
||||
|
||||
### States
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| **Draft** | Author is writing the proposal. Not yet ready for formal review. |
|
||||
| **Under Review** | PR is open. Maintainers and community are discussing the design. |
|
||||
| **Accepted** | Maintainers have approved the design. Implementation can begin. |
|
||||
| **Declined** | Maintainers have decided not to pursue this proposal. The PEP remains in the repo for historical reference with an explanation of the decision. |
|
||||
| **Deferred** | Good idea, but not the right time. Will be reconsidered later. |
|
||||
| **Withdrawn** | Author has decided not to pursue this proposal. |
|
||||
| **Implementing** | Accepted and actively being built. Linked to tracking issue(s). |
|
||||
| **Complete** | Fully implemented and released. |
|
||||
|
||||
## How to Submit a PEP
|
||||
|
||||
### 1. Discuss First (Recommended)
|
||||
|
||||
Before writing a full PEP, validate the idea:
|
||||
|
||||
- Open a [GitHub Discussion](https://github.com/katanemo/plano/discussions) describing the problem and your proposed approach
|
||||
- Or bring it up in a [community meeting](https://discord.gg/pGZf2gcwEc)
|
||||
- Or open a GitHub issue tagged `enhancement`
|
||||
|
||||
This step saves time by catching fundamental objections early.
|
||||
|
||||
### 2. Write the PEP
|
||||
|
||||
Copy `docs/peps/PEP-TEMPLATE.md` to `docs/peps/PEP-XXXX-short-title.md` (use the next available number). Fill in all sections. The template is deliberately structured — each section exists for a reason.
|
||||
|
||||
Key guidelines:
|
||||
|
||||
- **Be specific.** "Add caching" is too vague. "Add exact-match response cache with configurable TTL keyed by model + message hash" is actionable.
|
||||
- **Show the config.** If the feature involves user-facing configuration, include the YAML snippet users would write.
|
||||
- **Address trade-offs.** Every design has trade-offs. Acknowledging them strengthens the proposal.
|
||||
- **Include alternatives.** Explain what other approaches you considered and why you chose this one.
|
||||
|
||||
### 3. Submit as a Pull Request
|
||||
|
||||
Open a PR adding your PEP file to `docs/peps/`. The PR title should be `PEP-XXXX: Short Title`. Set the status to `Draft` or `Under Review` depending on readiness.
|
||||
|
||||
### 4. Review and Discussion
|
||||
|
||||
- At least **two maintainers** must review the PEP
|
||||
- Community members are encouraged to comment on the PR
|
||||
- The author is expected to respond to feedback and revise the proposal
|
||||
- Discussion should focus on the **design**, not implementation details (those belong in code review)
|
||||
- Complex PEPs may be discussed in a community meeting
|
||||
|
||||
### 5. Decision
|
||||
|
||||
Maintainers aim to provide **initial feedback within two weeks** of a PEP entering `Under Review`. Complex proposals may take longer, but the author should never be left without a response.
|
||||
|
||||
A PEP is **accepted** when at least two maintainers approve the PR and there are no unresolved objections. The accepting maintainer merges the PR with the status set to `Accepted`.
|
||||
|
||||
A PEP is **declined** when maintainers determine the proposal doesn't align with the project's direction or has fundamental issues that can't be resolved. The PR is merged (not closed) with the status set to `Declined` and a rationale recorded — declined PEPs remain in the repo as a record.
|
||||
|
||||
**Resolving disagreements:** If maintainers disagree on a PEP, the proposal is discussed in a community meeting. If consensus still can't be reached, the project lead makes the final call and records the rationale in the PEP.
|
||||
|
||||
### 6. Implementation
|
||||
|
||||
Once accepted:
|
||||
|
||||
- Create a tracking GitHub issue (or issues) for the implementation
|
||||
- Link the issue(s) in the PEP header
|
||||
- Update the PEP status to `Implementing`
|
||||
- Implementation PRs should reference the PEP number (e.g., "Part of PEP-0042")
|
||||
- When all implementation work is merged and released, update status to `Complete`
|
||||
|
||||
## PEP Numbering
|
||||
|
||||
- PEPs are numbered sequentially starting from 0001
|
||||
- PEP-0000 is reserved for this process document
|
||||
- The author picks the next available number when submitting
|
||||
|
||||
## Roles
|
||||
|
||||
| Role | Responsibility |
|
||||
|---|---|
|
||||
| **Author** | Writes the PEP, responds to review feedback, drives the proposal to a decision |
|
||||
| **Sponsor** | A maintainer who shepherds the PEP through review. Required for PEPs from non-maintainers. Find a sponsor by asking in Discord or a community meeting. |
|
||||
| **Reviewers** | Maintainers and community members who provide feedback on the design |
|
||||
|
||||
## Amending Accepted PEPs
|
||||
|
||||
If an accepted PEP needs material changes during implementation:
|
||||
|
||||
- For minor adjustments (implementation details, clarifications): update the PEP in-place via a PR
|
||||
- For significant design changes: open a new PEP that supersedes the original, linking back to it
|
||||
|
||||
## Index
|
||||
|
||||
| PEP | Title | Status | Author |
|
||||
|---|---|---|---|
|
||||
| [0000](PEP-0000-process.md) | Plano Enhancement Proposal Process | Active | Plano Maintainers |
|
||||
171
docs/peps/PEP-TEMPLATE.md
Normal file
171
docs/peps/PEP-TEMPLATE.md
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
# PEP-XXXX: Title
|
||||
|
||||
<!--
|
||||
Instructions:
|
||||
1. Copy this file to PEP-XXXX-short-title.md (pick the next available number)
|
||||
2. Fill in all sections below
|
||||
3. Submit as a PR to docs/peps/
|
||||
4. Delete these instructions before submitting
|
||||
-->
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **PEP** | XXXX |
|
||||
| **Title** | |
|
||||
| **Status** | Draft |
|
||||
| **Author(s)** | Name (@github-handle) |
|
||||
| **Sponsor** | _(required for non-maintainers)_ |
|
||||
| **Created** | YYYY-MM-DD |
|
||||
| **Tracking Issue** | _(filled after acceptance)_ |
|
||||
| **Target Release** | _(filled after acceptance)_ |
|
||||
|
||||
## Summary
|
||||
|
||||
<!--
|
||||
One paragraph. What is this proposal, and why should someone care?
|
||||
A reader should be able to decide whether to keep reading from this section alone.
|
||||
-->
|
||||
|
||||
## Motivation
|
||||
|
||||
<!--
|
||||
Why is this change needed? What problem does it solve? Who benefits?
|
||||
Include concrete examples or user stories where possible.
|
||||
Link to GitHub issues, Discord discussions, or community meeting notes that motivated this proposal.
|
||||
-->
|
||||
|
||||
### Goals
|
||||
|
||||
<!--
|
||||
Bulleted list of what this PEP aims to achieve.
|
||||
-->
|
||||
|
||||
### Non-Goals
|
||||
|
||||
<!--
|
||||
Bulleted list of what this PEP explicitly does NOT aim to achieve.
|
||||
Being clear about scope prevents scope creep during review and implementation.
|
||||
-->
|
||||
|
||||
## Design
|
||||
|
||||
<!--
|
||||
The core of the proposal. Describe the technical design in enough detail that:
|
||||
1. Someone familiar with the codebase could implement it
|
||||
2. Someone unfamiliar could understand the approach and trade-offs
|
||||
|
||||
Structure this section however makes sense for your proposal. Common subsections:
|
||||
-->
|
||||
|
||||
### User-Facing Configuration
|
||||
|
||||
<!--
|
||||
If this feature involves configuration changes, show the YAML that users would write.
|
||||
Include a complete, working example — not pseudocode.
|
||||
-->
|
||||
|
||||
```yaml
|
||||
# Example configuration
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
<!--
|
||||
How does this fit into Plano's existing architecture?
|
||||
Which crates/components are affected? What's the data flow?
|
||||
Diagrams are welcome (use Mermaid or link to an image).
|
||||
-->
|
||||
|
||||
### API Changes
|
||||
|
||||
<!--
|
||||
Any new or changed HTTP endpoints, headers, or response formats.
|
||||
-->
|
||||
|
||||
### Behavior
|
||||
|
||||
<!--
|
||||
Describe the runtime behavior in detail.
|
||||
What happens on the happy path? What happens on errors?
|
||||
How does this interact with existing features (routing, streaming, tracing, etc.)?
|
||||
-->
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
<!--
|
||||
What other approaches did you evaluate? Why did you choose this design over them?
|
||||
This section demonstrates thoroughness and helps reviewers understand the design space.
|
||||
|
||||
For each alternative:
|
||||
- Brief description of the approach
|
||||
- Why it was rejected (trade-offs, complexity, limitations)
|
||||
-->
|
||||
|
||||
## Compatibility
|
||||
|
||||
<!--
|
||||
Does this change break any existing behavior? If so:
|
||||
- What breaks?
|
||||
- What's the migration path?
|
||||
- Should there be a deprecation period?
|
||||
|
||||
If this is purely additive, say so explicitly.
|
||||
-->
|
||||
|
||||
## Observability
|
||||
|
||||
<!--
|
||||
How will operators know this feature is working correctly?
|
||||
- New metrics, traces, or log entries?
|
||||
- Integration with existing Agentic Signals?
|
||||
- Dashboard or alerting recommendations?
|
||||
-->
|
||||
|
||||
## Security Considerations
|
||||
|
||||
<!--
|
||||
Does this change affect Plano's security posture?
|
||||
- New attack surfaces?
|
||||
- Authentication/authorization implications?
|
||||
- Data handling (PII, credentials, etc.)?
|
||||
|
||||
If not applicable, briefly explain why.
|
||||
-->
|
||||
|
||||
## Test Plan
|
||||
|
||||
<!--
|
||||
How will this be tested?
|
||||
- Unit tests (which crates?)
|
||||
- Integration tests
|
||||
- E2E tests (new demo or test scenario?)
|
||||
- Performance/load testing considerations
|
||||
|
||||
Be specific enough that a reviewer can evaluate coverage.
|
||||
-->
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
<!--
|
||||
How will this be implemented? Suggested breakdown:
|
||||
- Phases or PRs (if the work is large enough to split)
|
||||
- Which crates/files are primarily affected
|
||||
- Estimated complexity (small / medium / large)
|
||||
- Any dependencies on other work
|
||||
-->
|
||||
|
||||
## Open Questions
|
||||
|
||||
<!--
|
||||
Unresolved design questions that you'd like feedback on during review.
|
||||
Number them so reviewers can reference specific questions.
|
||||
|
||||
Remove this section (or mark all as resolved) before the PEP is accepted.
|
||||
-->
|
||||
|
||||
## References
|
||||
|
||||
<!--
|
||||
Links to related GitHub issues, discussions, external documentation,
|
||||
research papers, or prior art in other projects.
|
||||
-->
|
||||
Loading…
Add table
Add a link
Reference in a new issue