ipng/vppcfg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add contributing guide with a few baseline expectations

Browse Source
This commit is contained in:
Pim van Pelt
2022-04-07 20:57:51 +00:00
parent a8ced1b982
commit 771d1ba62f
1 changed files with 103 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
docs/contributing.md Normal file
View File

@ -0,0 +1,103 @@
## Contributing Code
We'd love to accept your patches and contributions to this project. There are a just a few
small guidelines you need to follow.
1. It's generally best to starting a new thread on vpp-dev@lists.fd.io in which you describe
the bug you're intending to fix, or the feature you're intending to add. Even if you think
it's relatively minor, it's helpful to know what people are working on. Mention in your mail
that you are planning to work on that bug or feature so that it can be attributed to you.
1. Follow the normal process of cloning the project, and setup a new branch to work in. It's
important that each group of changes be done in separate branches in order to ensure that a
pull request only includes the commits related to that bug or feature.
*NOTE*: We follow VPP's general contribution workflow described [here](https://wiki.fd.io/view/VPP/Pulling,_Building,_Running,_Hacking_and_Pushing_VPP_Code)
1. Any significant changes should always be accompanied by tests. The project already has good
test coverage, so look at some of the existing tests if you're unsure how to go about it.
Particularly relevant are config syntax and semantic validation, which will be expected to
have (a) full test coverage and (b) not negatively impact other configuration elements. If
in doubt, discuss the trade-offs on the mailinglist first.
1. All contributions must be licensed Apache 2.0 and all source code files must have a copy of
the boilerplate licence comment with author and copyright attribution. 'Signed-off-by' field
is required for all contributions, signalling Developer Certificate of Origin 1.1 (commonly
used by VPP and originally from the Linux kernel).
1. Do your best to have well-formed commit messages for each change. This provides consistency
throughout the project, and ensures that commit messages are able to be formatted properly
by various git tools.
Finally, push the commits to your fork and submit a pull request (GitHub) or commit them to
gerrit.fd.io and request a review (Gerrit).
```
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
```
### Semantic validation
`vppcfg` will be used in many different scenarios - from the bench just doing a quick test
when hacking on a VPP feature, all the way through to large production networks where dataplane
crashes cause user harm. As such, contributing code has to be done with care.
Static analysis is incredibly important, to help ensure that the YAML configuration files can
be safely applied to running VPP instances:
* All changes to syntax validation are expected to have 100% unit test coverage.
* All changes to semantic validation are expected to have 100% YAMLTest coverage.
* New code cannot break an existing test unless the test is objectively incorrect.
### Completeness
Feature additions are expected to be reasonably complete when merged. Keep work-in-progress in
a git branch until it's completed. New VPP APIs should have:
* A config schema and semantic validation (`vppcfg check`)
* A config reader (`vppcfg dump`)
* A config planner (`vppcfg plan`)
* A config applier (`vppcfg apply`)
* A reasonable N-way integration test (moving between various YAML configuration states without
crashing `vppcfg` or VPP itself)
* Demonstrably work well with existing code.
### Version Skew
`vppcfg` is intended to work within two major releases of VPP. For example, 21.10 and 22.02 will
be supported until 22.06 releases, after which 21.10 will no longer be supported and `vppcfg`
will print a warning. Best effort will be applied to ensuring that `vppcfg` works at each major
release window, in other words when VPP 22.06 releases, it is expected that `vppcfg` will pass
all unit- and regression/integration tests upon its release. It will then be tagged (and in the
future, likely released in tandem with VPP itself).
Workarounds in the `vppcfg` code will be tolerated within this two major releases time window.
To avoid technical debt, features will be asked to sync-to-latest when they have workarounds,
TODOs and special-cases that are VPP-version dependent, and they are eligable for removal if
they do not keep up with HEAD.
*NOTE*: Support is unlikely to be tractable in the case of any WARNING/ERROR states noted by
`vppcfg`. The API controlsurface of VPP is considerable, and at times `vppcfg` takes an opinionated
stance by recommending against configuration patterns even if they are strictly valid in VPP
(for example, setting an MTU on a BVI different to the bridge member interfaces). Operators
and code contributions should be strict in their semantic validation, with the intent of making
errors/bugs/crashes less likely in production.