mirror of
https://github.com/kubevela/kubevela.git
synced 2026-02-14 10:00:06 +00:00
refine our contributing guides (#1807)
* refine our contribute guides * Update CONTRIBUTING.md Co-authored-by: Hongchao Deng <hongchaodeng1@gmail.com> Co-authored-by: Hongchao Deng <hongchaodeng1@gmail.com>
This commit is contained in:
Jianbo Sun
GitHub
8
contribute/README.md
Normal file
8
contribute/README.md
Normal file
@@ -0,0 +1,8 @@
|
||||
# Contribute
|
||||
|
||||
This directory contains guides for contributors to the KubeVela project.
|
||||
|
||||
* [Create a pull request](./create-pull-request.md)
|
||||
* [Developer guide](./developer-guide.md)
|
||||
* [Triage issues](./triage-issues.md)
|
||||
* [Code conventions](./coding-conventions.md)
|
||||
162
contribute/coding-conventions.md
Normal file
162
contribute/coding-conventions.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# KubeVela code conventions
|
||||
|
||||
- Bash
|
||||
|
||||
- https://google.github.io/styleguide/shell.xml
|
||||
|
||||
- Ensure that build, release, test, and cluster-management scripts run on
|
||||
macOS
|
||||
|
||||
- Go
|
||||
|
||||
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
|
||||
|
||||
- [Effective Go](https://golang.org/doc/effective_go.html)
|
||||
|
||||
- Know and avoid [Go landmines](https://gist.github.com/lavalamp/4bd23295a9f32706a48f)
|
||||
|
||||
- Comment your code.
|
||||
- [Go's commenting conventions](http://blog.golang.org/godoc-documenting-go-code)
|
||||
- If reviewers ask questions about why the code is the way it is, that's a
|
||||
sign that comments might be helpful.
|
||||
|
||||
- Command-line flags should use dashes, not underscores
|
||||
|
||||
- Naming
|
||||
- Please consider package name when selecting an interface name, and avoid
|
||||
redundancy.
|
||||
|
||||
- e.g.: `storage.Interface` is better than `storage.StorageInterface`.
|
||||
|
||||
- Do not use uppercase characters, underscores, or dashes in package
|
||||
names.
|
||||
- Please consider parent directory name when choosing a package name.
|
||||
|
||||
- so pkg/controllers/autoscaler/foo.go should say `package autoscaler`
|
||||
not `package autoscalercontroller`.
|
||||
- Unless there's a good reason, the `package foo` line should match
|
||||
the name of the directory in which the .go file exists.
|
||||
- Importers can use a different name if they need to disambiguate.
|
||||
|
||||
- Locks should be called `lock` and should never be embedded (always `lock
|
||||
sync.Mutex`). When multiple locks are present, give each lock a distinct name
|
||||
following Go conventions - `stateLock`, `mapLock` etc.
|
||||
|
||||
- KubeVela also follows the Kubernetes conventions
|
||||
|
||||
- [API changes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md)
|
||||
|
||||
- [API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md)
|
||||
|
||||
## Testing conventions
|
||||
|
||||
- All new packages and most new significant functionality must come with unit
|
||||
tests
|
||||
|
||||
- Table-driven tests are preferred for testing multiple scenarios/inputs; for
|
||||
example, see [TestNamespaceAuthorization](https://git.k8s.io/kubernetes/test/integration/auth/auth_test.go)
|
||||
|
||||
- Unit tests must pass on macOS and Windows platforms - if you use Linux
|
||||
specific features, your test case must either be skipped on windows or compiled
|
||||
out (skipped is better when running Linux specific commands, compiled out is
|
||||
required when your code does not compile on Windows).
|
||||
|
||||
- Avoid relying on Docker hub (e.g. pull from Docker hub). Use gcr.io instead.
|
||||
|
||||
- Avoid waiting for a short amount of time (or without waiting) and expect an
|
||||
asynchronous thing to happen (e.g. wait for 1 seconds and expect a Pod to be
|
||||
running). Wait and retry instead.
|
||||
|
||||
- Significant features should come with integration (test/integration) and/or
|
||||
end-to-end (e2e/) tests. TOOD(@wonderflow): add detail test guides.
|
||||
- Including new vela cli commands and major features of existing commands
|
||||
|
||||
|
||||
## Directory and file conventions
|
||||
|
||||
- Avoid package sprawl. Find an appropriate subdirectory for new packages.
|
||||
- Libraries with no more appropriate home belong in new package
|
||||
subdirectories of pkg/util
|
||||
|
||||
- Avoid general utility packages. Packages called "util" are suspect. Instead,
|
||||
derive a name that describes your desired function. For example, the utility
|
||||
functions dealing with waiting for operations are in the "wait" package and
|
||||
include functionality like Poll. So the full name is wait.Poll
|
||||
|
||||
- All filenames should be lowercase
|
||||
|
||||
- Go source files and directories use underscores, not dashes
|
||||
- Package directories should generally avoid using separators as much as
|
||||
possible (when packages are multiple words, they usually should be in nested
|
||||
subdirectories).
|
||||
|
||||
- Document directories and filenames should use dashes rather than underscores
|
||||
|
||||
- Contrived examples that illustrate system features belong in
|
||||
/docs/user-guide or /docs/admin, depending on whether it is a feature primarily
|
||||
intended for users that deploy applications or cluster administrators,
|
||||
respectively. Actual application examples belong in /examples.
|
||||
- Examples should also illustrate [best practices for configuration and using the system](https://kubernetes.io/docs/concepts/configuration/overview/)
|
||||
|
||||
- Third-party code
|
||||
|
||||
- Go code for normal third-party dependencies is managed using
|
||||
[go modules](https://github.com/golang/go/wiki/Modules)
|
||||
|
||||
- Other third-party code belongs in `/third_party`
|
||||
- forked third party Go code goes in `/third_party/forked`
|
||||
- forked _golang stdlib_ code goes in `/third_party/forked/golang`
|
||||
|
||||
- Third-party code must include licenses
|
||||
|
||||
- This includes modified third-party code and excerpts, as well
|
||||
|
||||
## Logging Conventions
|
||||
|
||||
### Structured logging
|
||||
|
||||
We recommend using `klog.InfoS` to structure the log. The `msg` argument need start from a capital letter.
|
||||
and name arguments should always use lowerCamelCase.
|
||||
|
||||
```golang
|
||||
// func InfoS(msg string, keysAndValues ...interface{})
|
||||
klog.InfoS("Reconcile traitDefinition", "traitDefinition", klog.KRef(req.Namespace, req.Name))
|
||||
// output:
|
||||
// I0605 10:10:57.308074 22276 traitdefinition_controller.go:59] "Reconcile traitDefinition" traitDefinition="vela-system/expose"
|
||||
```
|
||||
|
||||
### Use `klog.KObj` and `klog.KRef` for Kubernetes objects
|
||||
|
||||
`klog.KObj` and `klog.KRef` can unify the output of kubernetes object.
|
||||
|
||||
```golang
|
||||
// KObj is used to create ObjectRef when logging information about Kubernetes objects
|
||||
klog.InfoS("Start to reconcile", "appDeployment", klog.KObj(appDeployment))
|
||||
// KRef is used to create ObjectRef when logging information about Kubernetes objects without access to metav1.Object
|
||||
klog.InfoS("Reconcile application", "application", klog.KRef(req.Namespace, req.Name))
|
||||
```
|
||||
|
||||
### Logging Level
|
||||
|
||||
[This file](https://github.com/oam-dev/kubevela/blob/master/pkg/controller/common/logs.go) contains KubeVela's log level,
|
||||
you can set the log level by `klog.V(level)`.
|
||||
|
||||
```golang
|
||||
// you can use klog.V(common.LogDebug) to print debug log
|
||||
klog.V(common.LogDebug).InfoS("Successfully applied components", "workloads", len(workloads))
|
||||
```
|
||||
|
||||
Looking for more details in [Structured Logging Guide](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/migration-to-structured-logging.md#structured-logging-in-kubernetes).
|
||||
|
||||
|
||||
## Linting and formatting
|
||||
|
||||
To ensure consistency across the Go codebase, we require all code to pass a number of linter checks.
|
||||
|
||||
To run all linters, use the `reviewable` Makefile target:
|
||||
|
||||
```shell script
|
||||
make reviewable
|
||||
```
|
||||
|
||||
The command will clean code along with some lint checks. Please remember to check in all changes after that.
|
||||
86
contribute/create-pull-request.md
Normal file
86
contribute/create-pull-request.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# Create a pull request
|
||||
|
||||
We're excited that you're considering making a contribution to the KubeVela project!
|
||||
This document guides you through the process of creating a [pull request](https://help.github.com/en/articles/about-pull-requests/).
|
||||
|
||||
## Before you begin
|
||||
|
||||
We know you're excited to create your first pull request. Before we get started, read these resources first:
|
||||
|
||||
- Learn how to start [Contributing to KubeVela](/CONTRIBUTING.md).
|
||||
- Make sure your code follows the relevant [style guides](/contribute/style-guides).
|
||||
|
||||
## Your first pull request
|
||||
|
||||
If this is your first time contributing to an open-source project on GitHub, make sure you read about [Creating a pull request](https://help.github.com/en/articles/creating-a-pull-request).
|
||||
|
||||
To increase the chance of having your pull request accepted, make sure your pull request follows these guidelines:
|
||||
|
||||
- Title and description matches the implementation.
|
||||
- Commits within the pull request follow the [Formatting guidelines](#Formatting-guidelines).
|
||||
- The pull request closes one related issue.
|
||||
- The pull request contains necessary tests that verify the intended behavior.
|
||||
- If your pull request has conflicts, rebase your branch onto the main branch.
|
||||
|
||||
If the pull request fixes a bug:
|
||||
|
||||
- The pull request description must include `Closes #<issue number>` or `Fixes #<issue number>`.
|
||||
- To avoid regressions, the pull request should include tests that replicate the fixed bug.
|
||||
|
||||
Please refer to the [code conventions](/contribute/coding-conventions.md) for better code style and conventions.
|
||||
|
||||
## Code review
|
||||
|
||||
Once you've created a pull request, the next step is to have someone review your change.
|
||||
A review is a learning opportunity for both the reviewer and the author of the pull request.
|
||||
|
||||
If you think a specific person needs to review your pull request, then you can tag them in the description or in a comment.
|
||||
Tag a user by typing the `@` symbol followed by their GitHub username.
|
||||
|
||||
We recommend that you read [How to do a code review](https://google.github.io/eng-practices/review/reviewer/) to learn more about code reviews.
|
||||
|
||||
## Formatting guidelines
|
||||
|
||||
A well-written pull request minimizes the time to get your change accepted.
|
||||
These guidelines help you write good commit messages and descriptions for your pull requests.
|
||||
|
||||
### Commit message format
|
||||
|
||||
KubeVela uses the guidelines for commit messages outlined in [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/), with the following additions:
|
||||
|
||||
- Subject line must begin with the _area_ of the commit.
|
||||
- A footer in the form of an optional [keyword and issue reference](https://help.github.com/en/articles/closing-issues-using-keywords).
|
||||
|
||||
#### Area
|
||||
|
||||
The area should use upper camel case, e.g. UpperCamelCase.
|
||||
|
||||
Prefer using one of the following areas:
|
||||
|
||||
- **Application:** Changes to the application controller.
|
||||
- **Component:** Changes to the component related code or definition controller.
|
||||
- **Trait:** Changes to the trait related code or definition controller.
|
||||
- **CUE:** Changes to the CUE related logic.
|
||||
- **Docs:** Changes to documentation.
|
||||
- **AppConfig:** Changes to AppConfig related code.
|
||||
|
||||
**Examples**
|
||||
|
||||
- `Application: Support workflow in application controller`
|
||||
- `CUE: Fix patch parse issues`
|
||||
- `Docs: Changed url to URL in all documentation files`
|
||||
|
||||
### Pull request titles
|
||||
|
||||
The KubeVela team _squashes_ all commits into one when we accept a pull request.
|
||||
The title of the pull request becomes the subject line of the squashed commit message.
|
||||
We still encourage contributors to write informative commit messages, as they become a part of the Git commit body.
|
||||
|
||||
We use the pull request title when we generate change logs for releases. As such, we strive to make the title as informative as possible.
|
||||
|
||||
Make sure that the title for your pull request uses the same format as the subject line in the commit message.
|
||||
|
||||
### Pass all the CI checks
|
||||
|
||||
Before merge, All test CI should pass green.
|
||||
The `codecov/project` should also pass. This means the coverage should not drop. See [Codecov commit status](https://docs.codecov.io/docs/commit-status#project-status).
|
||||
145
contribute/developer-guide.md
Normal file
145
contribute/developer-guide.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Developer guide
|
||||
|
||||
This guide helps you get started developing KubeVela.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Golang version 1.16+
|
||||
2. Kubernetes version v1.18+ with `~/.kube/config` configured.
|
||||
3. ginkgo 1.14.0+ (just for [E2E test](./developer-guide.md#e2e-test))
|
||||
4. golangci-lint 1.38.0+, it will install automatically if you run `make`, you can [install it manually](https://golangci-lint.run/usage/install/#local-installation) if the installation is too slow.
|
||||
5. kubebuilder v2.3.0+
|
||||
|
||||
<details>
|
||||
<summary>Install Kubebuilder manually</summary>
|
||||
|
||||
linux:
|
||||
```
|
||||
wget https://github.com/kubernetes-sigs/kubebuilder/releases/download/v2.3.1/kubebuilder_2.3.1_linux_amd64.tar.gz
|
||||
tar -zxvf kubebuilder_2.3.1_linux_amd64.tar.gz
|
||||
mkdir -p /usr/local/kubebuilder/bin
|
||||
sudo mv kubebuilder_2.3.1_linux_amd64/bin/* /usr/local/kubebuilder/bin
|
||||
```
|
||||
|
||||
macOS:
|
||||
```
|
||||
wget https://github.com/kubernetes-sigs/kubebuilder/releases/download/v2.3.1/kubebuilder_2.3.1_darwin_amd64.tar.gz
|
||||
tar -zxvf kubebuilder_2.3.1_darwin_amd64.tar.gz
|
||||
mkdir -p /usr/local/kubebuilder/bin
|
||||
sudo mv kubebuilder_2.3.1_darwin_amd64/bin/* /usr/local/kubebuilder/bin
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
You may also be interested with KubeVela's [design](https://github.com/oam-dev/kubevela/tree/master/design/vela-core) before diving into its code.
|
||||
|
||||
## Build
|
||||
|
||||
* Clone this project
|
||||
|
||||
```shell script
|
||||
git clone git@github.com:oam-dev/kubevela.git
|
||||
```
|
||||
|
||||
KubeVela includes two parts, `vela core` and `vela cli`.
|
||||
|
||||
- The `vela core` is actually a K8s controller, it will watch OAM Spec CRD and deploy resources.
|
||||
- The `vela cli` is a command line tool that can build, run apps(with the help of `vela core`).
|
||||
|
||||
For local development, we probably need to build both of them.
|
||||
|
||||
* Build Vela CLI
|
||||
|
||||
```shell script
|
||||
make
|
||||
```
|
||||
|
||||
After the vela cli built successfully, `make` command will create `vela` binary to `bin/` under the project.
|
||||
|
||||
* Configure `vela` binary to System PATH
|
||||
|
||||
```shell script
|
||||
export PATH=$PATH:/your/path/to/project/kubevela/bin
|
||||
```
|
||||
|
||||
Then you can use `vela` command directly.
|
||||
|
||||
* Build Vela Core
|
||||
|
||||
```shell script
|
||||
make manager
|
||||
```
|
||||
|
||||
* Run Vela Core
|
||||
|
||||
Firstly make sure your cluster has CRDs, below is the command that can help install all CRDs.
|
||||
|
||||
```shell script
|
||||
make core-install
|
||||
```
|
||||
|
||||
Run locally:
|
||||
|
||||
```shell script
|
||||
make core-run
|
||||
```
|
||||
|
||||
This command will run controller locally, it will use your local KubeConfig which means you need to have a k8s cluster
|
||||
locally. If you don't have a one, we suggest that you could setup up a cluster with [kind](https://kind.sigs.k8s.io/).
|
||||
|
||||
When you're developing `vela-core`, make sure the controller installed by helm chart is not running.
|
||||
Otherwise, it will conflict with your local running controller.
|
||||
|
||||
You can check and uninstall it by using helm.
|
||||
|
||||
```shell script
|
||||
helm list -A
|
||||
helm uninstall -n vela-system kubevela
|
||||
```
|
||||
|
||||
## Use
|
||||
|
||||
You can try use your local built binaries follow [the documentation](https://kubevela.io/docs/quick-start).
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit test
|
||||
|
||||
```shell script
|
||||
make test
|
||||
```
|
||||
|
||||
### E2E test
|
||||
|
||||
**Before e2e test start, make sure you have vela-core running.**
|
||||
|
||||
```shell script
|
||||
make core-run
|
||||
```
|
||||
|
||||
Start to test.
|
||||
|
||||
```
|
||||
make e2e-test
|
||||
```
|
||||
|
||||
## Contribute Docs
|
||||
|
||||
Please read [the documentation](https://github.com/oam-dev/kubevela/tree/master/docs/README.md) before contributing to the docs.
|
||||
|
||||
- Build docs
|
||||
|
||||
```shell script
|
||||
make docs-build
|
||||
```
|
||||
|
||||
- Local development and preview
|
||||
|
||||
```shell script
|
||||
make docs-start
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
* Read our [code conventions](coding-conventions.md)
|
||||
* Learn how to [Create a pull request](create-pull-request.md)
|
||||
40
contribute/triage-issues.md
Normal file
40
contribute/triage-issues.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Triage issues
|
||||
|
||||
Triage helps ensure that issues resolve quickly by:
|
||||
|
||||
- Ensuring the issue's intent and purpose is conveyed precisely. This is necessary because it can be difficult for
|
||||
an issue to explain how an end user experiences a problem and what actions they took.
|
||||
- Giving a contributor the information they need before they commit to resolving an issue.
|
||||
- Lowering the issue count by preventing duplicate issues.
|
||||
- Streamlining the development process by preventing duplicate discussions.
|
||||
|
||||
This document gives you some ideas on what you can do to help. For more information, read more about [how the core KubeVela team triage issues](/ISSUE_TRIAGE.md).
|
||||
|
||||
## Improve issues
|
||||
|
||||
Improve issues by suggesting improvements to the title and description. If you think an issue has formatting issues,
|
||||
bad language, or grammatical errors, post a comment to let the author and maintainers know.
|
||||
|
||||
## Report resolved issues
|
||||
|
||||
If you think an issue has been resolved, or is no longer relevant, suggest us to close it.
|
||||
Add a comment on the issue, where you explain the reason it should be closed.
|
||||
Make sure to include any related issues and pull requests.
|
||||
|
||||
## Investigate issues
|
||||
|
||||
Investigate issues that we haven't been able to reproduce yet.
|
||||
In some cases, there are many combinations of usage that make it difficult for us to reproduce certain issues.
|
||||
Help us by adding more information.
|
||||
|
||||
## Vote on issues
|
||||
|
||||
Use [GitHub reactions](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments)
|
||||
to let us know what's important to you. Vote on bugs if you've experienced the same problem. **Don't vote, or react, by commenting on the issue.**
|
||||
|
||||
Read more about [how we prioritize issues](/ISSUE_TRIAGE.md#4-prioritization-of-issues).
|
||||
|
||||
## Report duplicates
|
||||
|
||||
If you find two issues that describe the same thing, add a comment in one of the issues, with a reference (`#<issue number>`) to the other.
|
||||
Explain why you think the issue is duplicated.
|
||||
Reference in New Issue
Block a user