Skip to content

Describe tip process #2909

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jenpaff wants to merge 4 commits into
base: main
Choose a base branch
from
+131 −6
Open

Describe tip process #2909

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
18d23b7
Describe tip process
jenpaff Feb 28, 2026
5db8629
Merge branch 'main' into jenpaff/tip-process
jenpaff Mar 2, 2026
70f68b5
Status definitions, review feedback
jenpaff Mar 3, 2026
8db63bd
Merge branch 'main' into jenpaff/tip-process
jenpaff Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions tips/ref-impls/spec_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ The goal is to define a specification that is clear, descriptive, and acts as th

- **Spec ID**: TIP-XXX
- **Authors/Owners**: <name/handle>
- **Status**: Draft | In Review | Approved | In Progress | Devnet | QA/Integration | Testnet | Mainnet | Deprecated
- **Status**: Draft | In Review | Ready for Consideration | Approved | Scheduled | Testnet | Mainnet
- **Related Specs**: <links or IDs>

---
Expand All @@ -19,6 +19,10 @@ Short 2–4 sentence high level summary

Explain what problem this solves/functionality this introduces, and any alternatives considered (if applicable). Add context or links to other specs/resources that serve as prerequisites to this spec.

## Assumptions

List the explicit assumptions this spec depends on (for example: upstream invariants, trust boundaries, deployment ordering, and backward compatibility expectations). Call out what happens if an assumption is violated.

---

# Specification
Expand All @@ -35,5 +39,3 @@ Where a feature involves multiple processes, state diagrams / flowcharts should
# Invariants

This section should describe invariants that must always hold, and outline the critical cases that the test suite must cover.


121 changes: 121 additions & 0 deletions tips/tip-0000.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
---
id: TIP-0000
title: TIP Process
description: Defines the Tempo Improvement Proposal lifecycle from draft to production.
authors: Internal
status: Draft
related: N/A
---

# TIP-0000: TIP Process

## Abstract

This TIP defines the end-to-end lifecycle for a Tempo Improvement Proposal, from drafting through mainnet rollout. It requires a clear owner, structured review (including security and implications), and an explicit decision at the network upgrade call before a TIP can be approved and scheduled. It also sets rollout expectations for technical communications, tooling implications, and success criteria monitoring.

**External TIP submissions are not accepted at this time.**

## Motivation

The goal of this doc is to create a shared understanding of the TIP process. Every TIP should go through the same stages and meet a consistent bar for security, quality, and user impact. The process emphasizes solving real user problems.

---

# Specification

## Status Lifecycle

`Draft` → `In Review` / `Rejected`

`In Review` → `Ready for Consideration` / `Rejected`

`Ready for Consideration` → `Approved` / `Backlog` / `Rejected`

`Backlog` → `Ready for Consideration` / `Rejected`

`Approved` → `Scheduled` → `Testnet` → `Mainnet`

`Draft` means the idea is being written as a TIP and is not yet open for formal review.

`In Review` means the TIP is open for structured technical, security, and implications review.

`Ready for Consideration` means review is complete and the TIP is ready for a decision on a network upgrade call.

`Backlog` means the TIP is high-quality and directionally supported, but is parked until there is clear customer or product pull.

`Approved` means the TIP is accepted and will be scheduled for an upcoming upgrade.

`Scheduled` means the TIP is assigned to a specific upgrade after capacity and upgrade scope are confirmed.

`Testnet` means the TIP ships in a testnet upgrade and is monitored against success criteria.

`Mainnet` means the TIP has shipped to mainnet.

`Rejected` means the TIP will not move forward in its current form.

## 1. Propose a TIP

Goal: Turn an idea into a concrete specification.

1. Share your idea and problem statement with the team, get feedback as early as possible.
2. Assign a single TIP owner (driver) responsible for moving the TIP forward.
Copy link
Contributor

@rakita rakita Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would consider for it to have one owner to manage the flow and a small working group of people for ack-ing decisions, eng/research/sec or two senior people from eng and one research (Group, of course, depends on TIP type).

3. Pick the lowest available TIP number and create branch `TIP/xxxx`.
4. Add `tip-xxxx.md` using the existing [TIP Template](./tip_template.md) and open a draft PR against the Tempo repository.
5. Iterate until the spec is complete; when it is ready for review, open the PR and set status to `In Review`.
6. Share the PR with the relevant stakeholders for review.

### TIP Owner Expectations

Each TIP must have a clear owner who drives it forward, keeps status visible, and stands behind the proposal and its rationale. The owner is responsible for resolving open questions before asking for approval, making sure product and communication implications are covered, and proactively unblocking decisions as the TIP moves through each stage.

### TIP Considerations

When drafting a TIP, clearly explain what the change is, why it is needed now, and which assumptions it depends on. Document the key design decisions, the alternatives you considered and rejected, and your threat model with concrete mitigations. Call out expected impact on existing tooling and users, and define success criteria with the metrics you will track before and after rollout.

## 2. Review the TIP

Goal: Validate the problem and design with stakeholders and ensure the TIP meets our bar for quality, security and impact.

1. Share the TIP for stakeholder review and keep the PR updated.
2. Provide evidence that the problem is real.
3. Provide evidence that the design is feasible and robust.
4. Complete a security review.
5. Complete an implications review that covers affected tooling, integrations, and partners. The outcome of the review should be shared with the respective stakeholders.
6. Run at least one whiteboard session to align context.
Copy link
Contributor

@rakita rakita Mar 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be higher in the list, sharing context is most important as it does onboarding and aligning of people to EIP. Maybe between 2 and 3. This allows security and core team to evaluate it very quickly.

Copy link
Contributor

@rakita rakita Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And additionally, before security review add engineering review.

7. Obtain engineering, research, and security approval.
8. Before merging, update status to `Ready for Consideration`, then merge.

## 3. Consideration and Decision

Goal: Move a `Ready for Consideration` TIP to a decision.

1. Once the TIP is `Ready for Consideration`, the TIP owner contacts the network upgrade call chair to add it to the next agenda.
2. The agenda entry must include a clear callout: `Decision required: Approve, Backlog, or Reject TIP-xxxx`.
3. The TIP owner prepares a concise summary of review feedback, tradeoffs, and spec changes.
4. The TIP owner explicitly asks for a decision during the call.

## 4. Network Upgrade Call

Purpose: Make decisions on TIPs.

1. Review each agenda TIP in `Ready for Consideration`.
2. The TIP owner presents the full case, including review feedback, tradeoffs, and spec changes.
3. Decide outcome: `Approved`, `Backlog`, or `Rejected`.
4. For approved TIPs, confirm the target upcoming upgrade when possible.
5. For backlogged TIPs, record the missing customer/product signal and revisit trigger.

Copy link
Contributor

@rakita rakita Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am missing a implementation stage here. Big changes to spec happens when during implementation and outcome of it can be fully changed TIP or even rejecting it as we found out something that does not work.

It should contain a definition of done, it should be heavy reviewed, it should pass resync/cyclops/internal audit etc.

This is additionally the most time consuming stage.

## 5. Scheduling Criteria

A TIP can move from `Approved` to `Scheduled` only if:

1. Engineering capacity is available.
2. The target upgrade is identified.
3. The rationale for inclusion timing is explicit (`Why include? Why now?`).
4. The TIP spec is complete as the technical source of truth, and written technical communication is prepared for rollout.

## 6. Testnet Release Readiness

Before releasing an upgrade to `Testnet`:

1. Publish written technical communication for the upgrade, including tooling changes and users that might be affected by the change.
2. Ensure dashboards and alerting are in place for success criteria.
8 changes: 5 additions & 3 deletions tips/tip_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ id: TIP-XXXX
title: TIP Title
description: Short description for SEO
authors: <name/handle>
status: Draft | In Review | Approved | In Progress | Devnet | QA/Integration | Testnet | Mainnet | Deprecated
status: Draft | In Review | Ready for Consideration | Approved | Scheduled | Testnet | Mainnet
related: <links or IDs>
protocolVersion: <version at which TIP is scheduled to be included/was included>
---
Expand All @@ -18,6 +18,10 @@ Short 2–4 sentence high level summary

Explain what problem this solves/functionality this introduces, and any alternatives considered (if applicable). Add context or links to other specs/resources that serve as prerequisites to this spec.

## Assumptions

List the explicit assumptions this spec depends on (for example: upstream invariants, trust boundaries, deployment ordering, and backward compatibility expectations). Call out what happens if an assumption is violated.

---

# Specification
Expand All @@ -34,5 +38,3 @@ Where a feature involves multiple processes, state diagrams / flowcharts should
# Invariants

This section should describe invariants that must always hold, and outline the critical cases that the test suite must cover.


Loading