109 lines
6.2 KiB
Markdown
109 lines
6.2 KiB
Markdown
## 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.
|
|
```
|
|
|
|
### 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.
|
|
|
|
### Testing Requirements
|
|
|
|
`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.
|
|
|
|
APIs integrations that require hardware, for example DPDK, RDMA or other custom hardware, are very
|
|
welcome in `vppcfg`. However, they must be tested / testable as well, so hardware must be made
|
|
available to testing rigs either remotely or locally, and integrated with release and integration
|
|
testing harnass to ensure continued support in releases. Contact the project tech lead to coordinate.
|
|
|
|
### 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.
|