diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..8638f2c --- /dev/null +++ b/docs/contributing.md @@ -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.