Add contributing guidelines

It came up on the monthly call that there is no strong guidelines for
this project on contribution, so this adds some.

Ideally contributors can fall back on this as a palce to get started
when submitting or reviewing changes.
This commit is contained in:
Brian Goff
2020-07-24 16:23:31 -07:00
parent af1df79088
commit 657e6aca77

View File

@@ -77,6 +77,70 @@ git remote add upstream git@github.com:virtual-kubelet/virtual-kubelet.git
```
3. Submit a pull request.
## Submission and Review guidelines
We welcome and appreciate everyone to submit and review changes. Here are some guidelines to follow for help ensure
a successful contribution experience.
Please note these are general guidelines, and while they are a good starting point, they are not specifically rules.
If you have a question about something, feel free to ask:
- [#virtual-kubelet](https://kubernetes.slack.com/archives/C8YU1QP8W) on Kubernetes Slack
- [virtualkubelet-dev@lists.cncf.io](mailto:virtualkubelet-dev@lists.cncf.io)
- GitHub Issues
#### Don't make breaking API changes.
Since Virtual Kubelet has reached 1.0 it is a major goal of the project to keep a stable API.
Breaking changes must only be considered if a 2.0 release is on the table, which should only come with thoughtful
consideration of the projects users as well as maintenance burden.
Also note that behavior changes in the runtime can have cascading effects that cause unintended failures. Behavior
changes should come well documented and with ample consideration for downstream effects. If possible, they should be
opt-in.
#### Public APIs
Public API's should be extendable and flexible without requiring breaking changes.
While we can always add a new function (`Foo2()`), a new type, etc, doing so makes it harder for people to update to
the new behavior.
Build API interfaces that do not need to be changed to adopt new or improved functionality. Opinions on how a particular
thing should work should be encoded by the user rather than implicit in the runtime. Defaults are fine, but defaults
should be overridable.
The smaller the surface area of an API, the easier it is to do more interesting things with it.
#### Building blocks
Don't overload functionality. If something is complicated to setup we can provide helpers or wrappers to do that, but
don't require users to do things a certain way because this tends to diminish the usefulness, especially as it relates
to runtimes.
We also do not want the maintenance burden of every users individual edge cases.
#### Use context.Context
Probably if it is a public/exported API, it should take a `context.Context`. Even if it doesn't need one today, it may
need it tomorrow, and then we have a breaking API change.
We use `context.Context` for storing loggers, tracing spans, and cancellation all across the project. Better safe
than sorry: add a `context.Context`.
#### Errors
Callers can't handle errors if they don't know what the error is, so make sure they can figure that out.
We use a package `errdefs` to define the types of errors we currently look out for. We do not typically look for
concrete error types, so check out `errdefs` and see if there is already an error type in there for your needs, or even
create a new one.
#### Testing
Ideally all behavior would be tested, in practice this is not the case. Unit tests are great, and fast. There is also
an end-to-end test suite for testing the overall behavior of the system. Please add tests. This is also a great place
to get started if you are new to the codebase.
## Code of conduct
Virtual Kubelet follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).