Add code and website guidelines (#2032)
* Add code and website guidelines Signed-off-by: Carlisia <carlisia@vmware.com> * Move other contrib info to documentation Signed-off-by: Carlisia <carlisia@vmware.com> * Fix typo Signed-off-by: Carlisia <carlisia@vmware.com> * Update doc Signed-off-by: Carlisia <carlisia@vmware.com>pull/2046/head
KubeKween
Nolan Brubaker
parent
4fb1bc2ef3
commit
3c6842bfe1
|
|
@ -1,70 +1,3 @@
|
|||
# Contributing
|
||||
|
||||
## CHANGELOG
|
||||
|
||||
Authors are expected to include a changelog file with their pull requests. The changelog file
|
||||
should be a new file created in the `changelogs/unreleased` folder. The file should follow the
|
||||
naming convention of `pr-username` and the contents of the file should be your text for the
|
||||
changelog.
|
||||
|
||||
velero/changelogs/unreleased <- folder
|
||||
000-username <- file
|
||||
|
||||
|
||||
## DCO Sign off
|
||||
|
||||
All authors to the project retain copyright to their work. However, to ensure
|
||||
that they are only submitting work that they have rights to, we are requiring
|
||||
everyone to acknowledge this by signing their work.
|
||||
|
||||
Any copyright notices in this repo should specify the authors as "the Velero contributors".
|
||||
|
||||
To sign your work, just add a line like this at the end of your commit message:
|
||||
|
||||
```
|
||||
Signed-off-by: Joe Beda <joe@heptio.com>
|
||||
```
|
||||
|
||||
This can easily be done with the `--signoff` option to `git commit`.
|
||||
|
||||
By doing this you state that you can certify the following (from https://developercertificate.org/):
|
||||
|
||||
```
|
||||
Developer Certificate of Origin
|
||||
Version 1.1
|
||||
|
||||
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
|
||||
1 Letterman Drive
|
||||
Suite D4700
|
||||
San Francisco, CA, 94129
|
||||
|
||||
Everyone is permitted to copy and distribute verbatim copies of this
|
||||
license document, but changing it is not allowed.
|
||||
|
||||
|
||||
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.
|
||||
```
|
||||
Authors are expected to follow some guidelines when submitting PRs. Please see [our documentation](https://velero.io/docs/master/code-standards/) for details.
|
||||
|
|
|
|||
|
|
@ -63,6 +63,10 @@ toc:
|
|||
url: /build-from-source
|
||||
- page: Run locally
|
||||
url: /run-locally
|
||||
- page: Code standards
|
||||
url: /code-standards
|
||||
- page: Website guidelines
|
||||
url: /website-guidelines
|
||||
- title: More information
|
||||
subfolderitems:
|
||||
- page: Backup file format
|
||||
|
|
|
|||
|
|
@ -0,0 +1,123 @@
|
|||
# Code Standards
|
||||
|
||||
## Adding a changelog
|
||||
|
||||
Authors are expected to include a changelog file with their pull requests. The changelog file
|
||||
should be a new file created in the `changelogs/unreleased` folder. The file should follow the
|
||||
naming convention of `pr-username` and the contents of the file should be your text for the
|
||||
changelog.
|
||||
|
||||
velero/changelogs/unreleased <- folder
|
||||
000-username <- file
|
||||
|
||||
Add that to the PR.
|
||||
|
||||
## Code
|
||||
|
||||
- Log messages are capitalized.
|
||||
|
||||
- Error messages are kept lower-cased.
|
||||
|
||||
- Wrap/add a stack only to errors that are being directly returned from non-velero code, such as an API call to the Kubernetes server.
|
||||
|
||||
```bash
|
||||
errors.WithStack(err)
|
||||
```
|
||||
|
||||
- Prefer to use the utilities in the Kubernetes package [`sets`](https://godoc.org/github.com/kubernetes/apimachinery/pkg/util/sets).
|
||||
|
||||
```bash
|
||||
k8s.io/apimachinery/pkg/util/sets
|
||||
```
|
||||
|
||||
## Imports
|
||||
|
||||
For imports, we use the following convention:
|
||||
|
||||
<group><version><api | client | informer | ...>
|
||||
|
||||
Example:
|
||||
|
||||
import (
|
||||
corev1api "k8s.io/api/core/v1"
|
||||
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
|
||||
corev1client "k8s.io/client-go/kubernetes/typed/core/v1"
|
||||
corev1listers "k8s.io/client-go/listers/core/v1"
|
||||
|
||||
velerov1api ""github.com/vmware-tanzu/velero/pkg/apis/velero/v1"
|
||||
velerov1client "github.com/vmware-tanzu/velero/pkg/generated/clientset/versioned/typed/velero/v1"
|
||||
)
|
||||
|
||||
## Mocks
|
||||
|
||||
We use a package to generate mocks for our interfaces.
|
||||
|
||||
Example: if you want to change this mock: https://github.com/vmware-tanzu/velero/blob/master/pkg/restic/mocks/restorer.go
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go get github.com/vektra/mockery/.../
|
||||
cd pkg/restic
|
||||
mockery -name=Restorer
|
||||
```
|
||||
|
||||
Might need to run `make update` to update the imports.
|
||||
|
||||
## DCO Sign off
|
||||
|
||||
All authors to the project retain copyright to their work. However, to ensure
|
||||
that they are only submitting work that they have rights to, we are requiring
|
||||
everyone to acknowledge this by signing their work.
|
||||
|
||||
Any copyright notices in this repo should specify the authors as "the Velero contributors".
|
||||
|
||||
To sign your work, just add a line like this at the end of your commit message:
|
||||
|
||||
```
|
||||
Signed-off-by: Joe Beda <joe@heptio.com>
|
||||
```
|
||||
|
||||
This can easily be done with the `--signoff` option to `git commit`.
|
||||
|
||||
By doing this you state that you can certify the following (from https://developercertificate.org/):
|
||||
|
||||
```
|
||||
Developer Certificate of Origin
|
||||
Version 1.1
|
||||
|
||||
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
|
||||
1 Letterman Drive
|
||||
Suite D4700
|
||||
San Francisco, CA, 94129
|
||||
|
||||
Everyone is permitted to copy and distribute verbatim copies of this
|
||||
license document, but changing it is not allowed.
|
||||
|
||||
|
||||
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.
|
||||
```
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
# Website Guidelines
|
||||
|
||||
## Running the website locally
|
||||
|
||||
When making changes to the website, please run the site locally before submitting a PR and manually verify your changes.
|
||||
|
||||
At the root of the project, run:
|
||||
|
||||
```bash
|
||||
make serve-docs
|
||||
```
|
||||
|
||||
This runs all the Ruby dependencies in a container.
|
||||
|
||||
Alternatively, for quickly loading the website, under the `velero/site/` directory run:
|
||||
|
||||
```bash
|
||||
bundle exec jekyll serve --livereload --future
|
||||
```
|
||||
|
||||
For more information on how to run the website locally, please see our [jekyll documentation](https://github.com/vmware-tanzu/velero/blob/master/site/README-JEKYLL.md).
|
||||
|
||||
## Adding a blog post
|
||||
|
||||
The `author_name` value must also be included in the tags field so the page that lists the author's posts will work properly (Ex: https://velero.io/tags/carlisia%20campos/).
|
||||
|
||||
Note that the tags field can have multiple values.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
author_name: Carlisia Campos
|
||||
tags: ['Carlisia Campos', "release", "how-to"]
|
||||
```
|
||||
|
||||
### Please add an image
|
||||
|
||||
If there is no image added to the header of the post, the default Velero logo will be used. This is fine, but not ideal.
|
||||
|
||||
If there's an image that can be used as the blog post icon, the image field must be set to:
|
||||
|
||||
```text
|
||||
image: /img/posts/<your_image_name.png>
|
||||
```
|
||||
|
||||
This image file must be added to the `/site/img/posts` folder.
|
||||
Loading…
Reference in New Issue