Skip to content

Commit 18433de

Browse files
npinaevanpinaeva
committed
Add "Enhancement Proposals" page explaining how to create NPEPs.
Add Meeting details to the "Community, discussion, contribution, and support" section, since this section is now linked from the enhancements page for existing ways to connect. Add npep folder and template. Most of the content is based on Gateway API src <3. Signed-off-by: Nadia Pinaeva <[email protected]>
1 parent 579435f commit 18433de

File tree

4 files changed

+139
-1
lines changed

4 files changed

+139
-1
lines changed

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ nav:
4242
- Reference:
4343
- Examples: reference/examples.md
4444
- API Reference: reference/spec.md
45+
- Enhancement Proposals: enhancements.md
4546

4647

4748
# (TODO)

‎npep/npep-95.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# NPEP-95: NPEP template
2+
3+
* Issue: [#95](https://github.com/kubernetes-sigs/network-policy-api/issues/95)
4+
* Status: Provisional
5+
6+
## TLDR
7+
8+
(1-2 sentence summary of the proposal)
9+
10+
## Goals
11+
12+
(Primary goals of this proposal.)
13+
14+
## Non-Goals
15+
16+
(What is out of scope for this proposal.)
17+
18+
## Introduction
19+
20+
(Can link to external doc -- but we should bias towards copying
21+
the content into the NPEP as online documents are easier to lose
22+
-- e.g. owner messes up the permissions, accidental deletion)
23+
24+
## API
25+
26+
(... details, can point to PR with changes)
27+
28+
## Conformance Details
29+
30+
(This section describes the names to be used for the feature or
31+
features in conformance tests and profiles.
32+
33+
These should be `CamelCase` names that specify the feature as
34+
precisely as possible, and are particularly important for
35+
Extended features, since they may be surfaced to users.)
36+
37+
## Alternatives
38+
39+
(List other design alternatives and why we did not go in that
40+
direction)
41+
42+
## References
43+
44+
(Add any additional document links. Again, we should try to avoid
45+
too much content not in version control to avoid broken links)

‎site-src/enhancements.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Network Policy Enhancement Proposal (NPEP)
2+
3+
Network Policy Enhancement Proposals (NPEP) serve a similar purpose to the [KEP][kep]
4+
process for the main Kubernetes project:
5+
6+
1. Ensure that changes to the API follow a known process and discussion
7+
in the OSS community.
8+
2. Make changes and proposals discoverable (current and future).
9+
3. Document design ideas, tradeoffs, decisions that were made for
10+
historical reference.
11+
12+
## Process
13+
14+
### 1. Discuss with the community
15+
Before creating a NPEP, share your high level idea with the community. Check
16+
[Community, discussion, contribution, and support](/#community-discussion-contribution-and-support)
17+
for the suitable communication option.
18+
19+
### 2. Create an Issue
20+
[Create a NPEP issue](https://github.com/kubernetes-sigs/network-policy-api/issues/new?assignees=&labels=kind%2Fenhancement&projects=&template=enhancement-proposal.md&title=%5BENHANCEMENT%5D)
21+
in the repo describing your change.
22+
At this point, you should copy the outcome of any other conversations or documents
23+
into this Issue.
24+
25+
### 3. Create a first PR for your NPEP
26+
NPEP process is supposed to be iterative, adding more details with every iteration.
27+
Every NPEP has a `Status` field, that is updated with the progress of NPEP.
28+
Current statuses are:
29+
30+
* "Provisional"
31+
* "Implementable"
32+
* "Standard"
33+
34+
they are described in more details further in this section.
35+
To start NPEP process, create a PR adding `npep-<issue number>.md` file in the
36+
[npep folder](https://github.com/kubernetes-sigs/network-policy-api/tree/master/npep)
37+
using the [template NPEP](https://github.com/kubernetes-sigs/network-policy-api/blob/master/npep/npep-95.md) as a starting point.
38+
39+
### 4. Provisional: Agree on the Goals
40+
Although it can be tempting to start writing out all the details of your
41+
proposal, it's important to first ensure we all agree on the goals. The first
42+
version of your NPEP should have "Provisional" status and leave out any implementation details,
43+
focusing primarily on "Goals" and "Non-Goals".
44+
45+
### 5. Implementable: Document Implementation Details
46+
Now that everyone agrees on the goals, it is time to start writing out your
47+
proposed implementation details. These implementation details should be very
48+
thorough, including the proposed API spec, and covering any relevant edge cases.
49+
Note that it may be helpful to use a shared doc for part of this phase to enable
50+
faster iteration on potential designs.
51+
52+
It is likely that throughout this process, you will discuss a variety of
53+
alternatives. Be sure to document all of these in the NPEP, and why we decided
54+
against them. At this stage, the NPEP should be targeting the "Implementable" stage.
55+
56+
### 6. Standard: Make API changes
57+
With the NPEP marked as "Implementable", it is time to actually make the proposed changes in our API.
58+
In some cases, these changes will be documentation
59+
only, but in most cases, some API changes will also be required.
60+
61+
When updating NPEP from "Implementable" to "Standard", status update may be the
62+
only required change, but also feel free to link any API, docs, etc. changes that
63+
were made as an implementation for a given NPEP.
64+
65+
Before changes are released they MUST be documented. NPEPs that have not been
66+
both implemented and documented before a release cut off will be excluded from
67+
the release.
68+
69+
70+
### 7. Close out the NPEP issue
71+
The NPEP issue should only be closed when the work is "done" (whatever
72+
that means for that NPEP).
73+
74+
## Out of scope
75+
76+
What is out of scope: see [text from KEP][kep-when-to-use]. Examples:
77+
78+
* Bug fixes
79+
* Small changes (API validation, documentation, fixups). It is always
80+
possible that the reviewers will determine a "small" change ends up
81+
requiring a NPEP.
82+
83+
[kep]: https://github.com/kubernetes/enhancements
84+
[kep-when-to-use]: https://github.com/kubernetes/enhancements/tree/master/keps#do-i-have-to-use-the-kep-process

‎site-src/index.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Network Policy API Working Group
22
👋 Welcome to the Network Policy API Project - we are happy to have you here! Before you get started here are some useful links:
3-
- [Bi-Weekly Meeting Agenda](https://docs.google.com/document/d/1AtWQy2fNa4qXRag9cCp5_HsefD7bxKe3ea2RPn8jnSs/edit#heading=h.ajvcztp6cza)
3+
44
- [NetworkPolicy v1 Docs](https://kubernetes.io/docs/concepts/services-networking/network-policies/)
5+
- [API reference spec](/reference/spec/)
56

67
## What is the Network Policy API Project?
78

@@ -33,9 +34,16 @@ multiple K8s CRD resources geared towards different users and use cases.
3334
Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
3435

3536
You can reach the maintainers of this project at:
37+
3638
- [Slack](https://kubernetes.slack.com/messages/sig-network-policy-api)
3739
- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-network)
3840

41+
The Network Policy API Meeting happens bi-weekly on Tuesday at 9am Pacific
42+
Time (16:00 UTC):
43+
44+
* [Zoom link](https://zoom.us/j/96264742248)
45+
* [Meeting Agenda](https://docs.google.com/document/d/1AtWQy2fNa4qXRag9cCp5_HsefD7bxKe3ea2RPn8jnSs/edit#heading=h.ajvcztp6cza)
46+
3947
To get started contributing please take time to read over the [contributing guidelines](https://github.com/kubernetes-sigs/network-policy-api/blob/master/CONTRIBUTING.md) as well as the [developer guide](https://github.com/kubernetes/community/blob/master/contributors/devel/README.md). You can then take a look at the open issues labelled 'good-first-issue' [here](https://github.com/kubernetes-sigs/network-policy-api/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
4048

4149
### Code of conduct

0 commit comments

Comments
 (0)