Draft P4PER#4 - P4PER Purpose and Guidelines by qobilidop · Pull Request #7 · p4lang/p4per

qobilidop · 2026-04-27T08:34:00Z

Tracking issue: #4

My goal here is to come up with a reasonable first draft. Further revisions are needed to move it from Draft to Active.

smolkaj

Looks great to me!!

A few questions and possible suggestions, all minor.

smolkaj · 2026-05-01T17:56:54Z

+
+## P4PER number
+
+A P4PER is uniquely identified by a number. To refer to a P4PER, use the format P4PER-N where N is the P4PER number. For example, this P4PER is P4PER-4.


Idea: Given that we use issue numbers to identify papers, perhaps P4PER#1234 is nicer (since # is what's used by github)?

Bonus: p4lang/p4per#123 will be understood by GitHub tooling!

Orthogonal nit: I find p4per signficantly easer to type than P4PER, so I'd prepfer p4per#123 as the canonical way to reference a paper.

I'm slightly against this, but open to change if more people prefer P4PER#4 or p4per#4. Let me make my arguments first:

p4per#4 aligns with the tracking issue p4lang/p4per#4, but it doesn't align with the URL or filename.

For the URL, something like p4per#4 is awkward to use, as it means going the the section named 4 on the page named p4per. It's much more conventional to use p4per-4, like what we do currently: https://p4lang.github.io/p4per/p4per-4/ (preview at https://p4lang.github.io/p4per/pr-preview/7/p4per-4/)

For a filename, p4per#4.md is awkward as well, it's more conventional to use p4per-4.md

These being said, we could keep using p4per-4 in URL and filename, but use P4PER#4/p4per#4 in text.

Looking at similar projects, I feel P4PER-N is more conventional in general. Examples:

EIP-1

KEP-555

Switched to use P4PER#N.

smolkaj · 2026-05-01T17:57:26Z

+
+A P4PER is uniquely identified by a number. To refer to a P4PER, use the format P4PER-N where N is the P4PER number. For example, this P4PER is P4PER-4.
+
+To get a unique number for your P4PER, create an issue in the [P4PER GitHub repo](https://github.com/p4lang/p4per), and use that issue number as your P4PER number.


issue, or PR, or both?
Both create unique IDs.

I imagine creating an issue may feel artifical, whereas one has to create a PR to submit a p4per anyhow?

I preferred issue as I think the lifetime of a P4PER might involve multiple PRs:

Creating and iterating on several versions of a Draft.

Getting it actually Accepted.

Having all the implementation done and marking it as Final.

Also, PRs in other repos can refer to this issue if they are part of the implementation.

What do you think?

Since you brought this up, now I realize these justifications are not obvious. So maybe it's worth adding them to the text directly.

@qobilidop What you describe sounds like something that can be done in a single PR, unless we have amendments?

I feel I failed to describe what I actually have in mind. So let me try again. Will update the text as well to make this clearer.

The main thing I want to argue for here is having a tracking issue per P4PER. This tracking issue serves the following purposes:

Unique P4PER number assignment.

Central hub to link to/from all related PRs/issues/links. Most importantly the PRs that create/update/implement the P4PER.

A thread for public discussion about this P4PER. For example, it could be that all the related PRs have been merged, but someone has something to bring up for discussion about this P4PER. Then this tracking issue is a natural place.

@fruffy Agree what I described in #7 (comment) could be done in a single PR usually. What I wanted to emphasize there (but didn't make it clear) was that some P4PERs might take a significantly long time period to fully develop and implement, like months or years. For these P4PERs, I'd prefer checking them in in Draft/Accepted status first, rather than having them in a PR for months/years until Final. #2 is a concrete example. I think it's already a well-written Draft. I'd prefer to check it in as a Draft. In the future when the authors are ready to push it forward, there could be follow-up PRs to turn it into Accepted/Final.

Does #7 (comment) address the concern here?

fruffy · 2026-05-11T21:58:23Z

Back from vacation, will try to give this a review by end of this week.

fruffy · 2026-05-15T18:05:30Z

+
+```mermaid
+flowchart LR
+    Draft --> Accepted


This is a rich process, but will we actually follow through with it? Or do we need it?

With implementation I assume you refer to other parts in P4Lang

This is a rich process, but will we actually follow through with it? Or do we need it?

Agree the current presentation is making the process more complicated than necessary. I'm working on a simplification:

I think the definition of each status is more important here. The transitions between statuses could be more flexible.

This flowchart is best viewed as a reference of the common status update progressions, in order to illustrate the relationships between the status. It doesn't mean each edge has to be a separate PR. If a P4PER author wants to go directly to Final in a single PR, that should be allowed.

With implementation I assume you refer to other parts in P4Lang

Yes, that's what I mean, essentially PRs in P4Lang repos like P4C, P4Runtime, BMv2, etc.

Does #7 (comment) address the concern here?

github-actions · 2026-05-16T19:53:03Z

Preview removed.

Signed-off-by: Bili Dong <qobilidop@gmail.com>

… style Signed-off-by: Bili Dong <qobilidop@gmail.com>

qobilidop · 2026-05-17T20:52:44Z

+    Active -.-> Final
+```
+
+### P4PER submission


@fruffy I rewrote this section for a simpler P4PER submission process. Does it look good to you now?

Signed-off-by: Bili Dong <qobilidop@gmail.com>

qobilidop · 2026-05-30T19:03:52Z

I think this P4PER is already in a good shape by Draft standards. I'm giving myself an editor approval and merging it. Will send a follow-up PR to ask for approver approval and move it from Draft to Active.

qobilidop requested review from fruffy, jafingerhut and smolkaj April 27, 2026 08:34

fruffy self-assigned this May 1, 2026

smolkaj approved these changes May 1, 2026

View reviewed changes

fruffy reviewed May 15, 2026

View reviewed changes

qobilidop force-pushed the p4per-4 branch 2 times, most recently from 06491a6 to 12cffbc Compare May 16, 2026 19:52

qobilidop mentioned this pull request May 17, 2026

Tracking issue for P4PER#4 - P4PER Purpose and Guidelines #4

Open

qobilidop added 2 commits May 17, 2026 13:28

Draft P4PER-4: P4PER Purpose and Guidelines

fea6a63

Signed-off-by: Bili Dong <qobilidop@gmail.com>

Refine and address some review comments

004efab

Signed-off-by: Bili Dong <qobilidop@gmail.com>

qobilidop force-pushed the p4per-4 branch from 87779ba to 004efab Compare May 17, 2026 20:28

Fix list indentation (4-space uniformly) according to Zensical/MkDocs…

a852423

… style Signed-off-by: Bili Dong <qobilidop@gmail.com>

qobilidop commented May 17, 2026

View reviewed changes

qobilidop added 2 commits May 17, 2026 13:55

Add "as of"

1d5c1fa

Signed-off-by: Bili Dong <qobilidop@gmail.com>

Use <...> for auto link rendering

fede706

Signed-off-by: Bili Dong <qobilidop@gmail.com>

qobilidop mentioned this pull request May 17, 2026

Number P4PERs after GitHub issues? #5

Closed

Switch from P4PER-N to P4PER#N

46ada14

Signed-off-by: Bili Dong <qobilidop@gmail.com>

qobilidop changed the title ~~Draft P4PER-4: P4PER Purpose and Guidelines~~ Draft P4PER#4 - P4PER Purpose and Guidelines May 22, 2026

qobilidop added 2 commits May 30, 2026 09:25

Refine draft

a3046ca

Signed-off-by: Bili Dong <qobilidop@gmail.com>

Further refine draft

3983984

Signed-off-by: Bili Dong <qobilidop@gmail.com>

qobilidop merged commit 855cdfa into p4lang:main May 30, 2026
2 checks passed

github-actions Bot added a commit that referenced this pull request May 30, 2026

Remove preview for PR #7

5ffc039

qobilidop deleted the p4per-4 branch May 31, 2026 17:57


		## P4PER number

		A P4PER is uniquely identified by a number. To refer to a P4PER, use the format P4PER-N where N is the P4PER number. For example, this P4PER is P4PER-4.


		A P4PER is uniquely identified by a number. To refer to a P4PER, use the format P4PER-N where N is the P4PER number. For example, this P4PER is P4PER-4.

		To get a unique number for your P4PER, create an issue in the [P4PER GitHub repo](https://github.com/p4lang/p4per), and use that issue number as your P4PER number.

Conversation

qobilidop commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smolkaj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qobilidop May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qobilidop May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qobilidop May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fruffy commented May 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qobilidop commented May 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

qobilidop commented Apr 27, 2026 •

edited

Loading

qobilidop May 17, 2026 •

edited

Loading

qobilidop May 1, 2026 •

edited

Loading

qobilidop May 17, 2026 •

edited

Loading

github-actions Bot commented May 16, 2026 •

edited

Loading