From 3c6842bfe163aba9133b9efcb5cee7a2a0db2718 Mon Sep 17 00:00:00 2001 From: KubeKween Date: Tue, 5 Nov 2019 08:23:47 -0800 Subject: [PATCH] Add code and website guidelines (#2032) * Add code and website guidelines Signed-off-by: Carlisia * Move other contrib info to documentation Signed-off-by: Carlisia * Fix typo Signed-off-by: Carlisia * Update doc Signed-off-by: Carlisia --- CONTRIBUTING.md | 69 +------------- site/_data/master-toc.yml | 4 + site/docs/master/code-standards.md | 123 +++++++++++++++++++++++++ site/docs/master/website-guidelines.md | 46 +++++++++ 4 files changed, 174 insertions(+), 68 deletions(-) create mode 100644 site/docs/master/code-standards.md create mode 100644 site/docs/master/website-guidelines.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ff296058..b42fcfafb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 -``` - -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. diff --git a/site/_data/master-toc.yml b/site/_data/master-toc.yml index 7e8570ca5..a05250313 100644 --- a/site/_data/master-toc.yml +++ b/site/_data/master-toc.yml @@ -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 diff --git a/site/docs/master/code-standards.md b/site/docs/master/code-standards.md new file mode 100644 index 000000000..594ba2d34 --- /dev/null +++ b/site/docs/master/code-standards.md @@ -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: + + + +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 +``` + +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. +``` diff --git a/site/docs/master/website-guidelines.md b/site/docs/master/website-guidelines.md new file mode 100644 index 000000000..49cfa703a --- /dev/null +++ b/site/docs/master/website-guidelines.md @@ -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/ +``` + +This image file must be added to the `/site/img/posts` folder.