Skip to content

Commit fdf177d

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #119 from npinaeva/npep-docs
Add documentation outlining the workflow process for opening a SIG-NET-PEP or NPEP
2 parents c82af30 + 18433de commit fdf177d

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)