github/kubevela
1
0
Fork 0
mirror of https://github.com/kubevela/kubevela.git synced 2026-02-14 10:00:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

refine our contributing guides (#1807)

Browse Source 
* 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
2021-06-16 20:56:19 +08:00
committed by GitHub
parent 649e0376cc
commit 046376aa1a
8 changed files with 808 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@@ -15,9 +15,9 @@ A clear and concise description of what the bug is.
**To Reproduce**
<!--
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
1. The YAML files of Component/Trait I used.
2. The YAML file of Application I applied.
3. Other operations I have done.
4. See error
-->
@@ -31,6 +31,12 @@ A clear and concise description of what you expected to happen.
If applicable, add screenshots to help explain your problem.
-->
**KubeVela Version**
<!--
Describe your KubeVela controller or CLI version information.
-->
**Cluster information**
<!--
Describe your kubernetes cluster information.

212
CONTRIBUTING.md
View File

@@ -4,205 +4,61 @@
KubeVela project is initialized and maintained by the cloud native community since day 0 with [bootstrapping contributors from 8+ different organizations](https://github.com/oam-dev/kubevela/graphs/contributors).
We intend for KubeVela to have an open governance since the very beginning and donate the project to neutral foundation as soon as it's released.
To help us create a safe and positive community experience for all, we require all participants to adhere to the [Code of Conduct](./CODE_OF_CONDUCT.md).
This doc explains how to set up a development environment, so you can get started
contributing to `kubevela` or build a PoC (Proof of Concept).
This document is a guide to help you through the process of contributing to KubeVela.
## Become a contributor
## Development
You can contribute to KubeVela in several ways. Here are some examples:
### Prerequisites
* Contribute to the KubeVela codebase.
* Report and triage bugs.
* Develop community CRD operators as workload or trait and contribute to [catalog](https://github.com/oam-dev/catalog).
* Write technical documentation and blog posts, for users and contributors.
* Organize meetups and user groups in your local area.
* Help others by answering questions about KubeVela.
1. Golang version 1.16+
2. Kubernetes version v1.16+ with `~/.kube/config` configured.
3. ginkgo 1.14.0+ (just for [E2E test](./CONTRIBUTING.md#e2e-test))
4. golangci-lint 1.31.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+
For more ways to contribute, check out the [Open Source Guides](https://opensource.guide/how-to-contribute/).
<details>
<summary>Install Kubebuilder manually</summary>
### Report bugs
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
```
Before submitting a new issue, try to make sure someone hasn't already reported the problem.
Look through the [existing issues](https://github.com/oam-dev/kubevela/issues) for similar issues.
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
```
Report a bug by submitting a [bug report](https://github.com/oam-dev/kubevela/issues/new?assignees=&labels=kind%2Fbug&template=bug_report.md&title=).
Make sure that you provide as much information as possible on how to reproduce the bug.
</details>
Follow the issue template and add additional information that will help us replicate the problem.
We also recommend you to learn about KubeVela's [design](https://kubevela.io/docs/concepts) before diving into its code.
#### Security issues
### Build
If you believe you've found a security vulnerability, please read our [security policy](https://github.com/oam-dev/kubevela/blob/master/SECURITY.md) for more details.
* Clone this project
### Suggest enhancements
```shell script
git clone git@github.com:oam-dev/kubevela.git
```
If you have an idea to improve KubeVela, submit an [feature request](https://github.com/oam-dev/kubevela/issues/new?assignees=&labels=kind%2Ffeature&template=feature_request.md&title=%5BFeature%5D).
KubeVela includes two parts, `vela core` and `vela cli`.
### Triage issues
- 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`).
If you don't have the knowledge or time to code, consider helping with _issue triage_. The community will thank you for saving them time by spending some of yours.
For local development, we probably need to build both of them.
Read more about the ways you can [Triage issues](/contribute/triage-issues.md).
* Build Vela CLI
### Answering questions
```shell script
make
```
If you have a question and you can't find the answer in the [documentation](https://kubevela.io/docs/),
the next step is to ask it on the [github discussion](https://github.com/oam-dev/kubevela/discussions).
After the vela cli built successfully, `make` command will create `vela` binary to `bin/` under the project.
It's important to us to help these users, and we'd love your help. You can help other KubeVela users by answering [their questions](https://github.com/oam-dev/kubevela/discussions).
* Configure `vela` binary to System PATH
### Your first contribution
```shell script
export PATH=$PATH:/your/path/to/project/kubevela/bin
```
Unsure where to begin contributing to KubeVela? Start by browsing issues labeled `good first issue` or `help wanted`.
Then you can use `vela` command directly.
- [Good first issue](https://github.com/oam-dev/kubevela/labels/good%20first%20issue) issues are generally straightforward to complete.
- [Help wanted](https://github.com/oam-dev/kubevela/labels/help%20wanted) issues are problems we would like the community to help us with regardless of complexity.
* Build Vela Core
If you're looking to make a code change, see how to set up your environment for [local development](contribute/developer-guide.md).
```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
```
## 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))
```
more detail in [Structured Logging Guide](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/migration-to-structured-logging.md#structured-logging-in-kubernetes).
## 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
```
## Make a pull request
Remember to write unit-test and e2e-test after you have finished your code.
Run following checks before making a pull request.
```shell script
make reviewable
```
The command will do some lint checks and clean code.
After that, check in all changes and send a pull request.
## Merge Regulations
Before merging, the pull request should obey the following rules:
- The commit title and message should be clear about what this PR does.
- All test CI should pass green.
- The `codecov/project` should pass. This means the coverage should not drop. See [Codecov commit status](https://docs.codecov.io/docs/commit-status#project-status).
When you're ready to contribute, it's time to [Create a pull request](/contribute/create-pull-request.md).

323
ISSUE_TRIAGE.md Normal file
View File

@@ -0,0 +1,323 @@
# Triage issues
The main goal of issue triage is to categorize all incoming KubeVela issues and make sure each issue has all basic
information needed for anyone else to understand and be able to start working on it.
> **Note:** This information is for OAM/KubeVela project Maintainers, Owners, and Admins.
> If you are a Contributor, then you will not be able to perform most of the tasks in this topic.
The core maintainers of the OAM/KubeVela project are responsible for categorizing all incoming issues and delegating
any critical or important issue to other maintainers. Currently one maintainer each week is responsible.
Besides that part, triage provides an important way to contribute to an open source project.
Triage helps ensure 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.
If you don't have the knowledge or time to code, consider helping with triage.
The community will thank you for saving them time by spending some of yours.
## Simplified flowchart diagram of the issue triage process
<!-- https://textik.com/#908a27a44c590528 -->
```
+-----------------------------+
| |
| New Issues Opened |
+-----------------+ |
| | Or More information needed |
| | |
| +--------------+--------------+
| Ask for more info |
| |
| +--------------+------------+
| | | Yes
| | All informatio needed |
| +-----------+ to categorize the issue？ +---------------+
| | No | | |
| | +---------------------------+ |
| | +-----------+-----------+ +---------------------------+
+------------+-----+-----+ | | Yes | |
| | | Needs investigation ？ +---------+ label: needs investigation|
| label: needs more info | | | | |
| | +----------+------------+ +-------------+-------------+
+------------------------+ | |
| No |
| |
+----------+----------+ investigate |
| label: type/* | |
| label: area/* +--------------------------+
| |
+--|-------------|----+
| | Yes
| +-------|-------------+ +-------------------+
| | needs priority？ +----+ label: priority/* |
| +-------|-------------+ +----------|--------+
| | No |
| | |
+----- ------|---+ +--|----- --+ |
| close issue + ---- + done +---------------------+
+----------------+ +-----------+
```
## 1. Find uncategorized issues
To get started with issue triage and finding issues that haven't been triaged you have two alternatives.
### Browse unlabeled issues
The easiest and straight forward way of getting started and finding issues that haven't been triaged is to browse
[unlabeled issues](https://github.com/oam-dev/kubevela/issues?q=is%3Aopen+is%3Aissue+no%3Alabel) and starting from
the bottom and working yourself to the top.
### Subscribe to all notifications
The more advanced, but recommended way is to subscribe to all notifications from this repository which means that
all new issues, pull requests, comments and important status changes are sent to your configured email address.
Read this [guide](https://help.github.com/en/articles/watching-and-unwatching-repositories#watching-a-single-repository)
for help with setting this up.
It's highly recommended that you setup filters to automatically remove emails from the inbox and label/categorize
them accordingly to make it easy for you to understand when you need to act upon a notification or where to look for
finding issues that haven't been triaged etc.
## 2. Ensure the issue contains basic information
Before triaging an issue very far, make sure that the issue's author provided the standard issue information.
This will help you make an educated recommendation on how to categorize the issue.
The KubeVela project utilizes [GitHub issue templates](https://help.github.com/en/articles/creating-issue-templates-for-your-repository)
to guide contributors to provide standard information that must be included for each type of template or type of issue.
### Standard issue information that must be included
Given a certain [issue template]([template](https://github.com/oam-dev/kubevela/issues/new/choose)) have been used
by the issue author or depending how the issue is perceived by the issue triage responsible, the following should
help you understand what standard issue information that must be included.
#### Bug reports
Should explain what happened, what was expected and how to reproduce it together with any additional information that
may help giving a complete picture of what happened such as screenshots, application related YAMLs, and any environment
related information that's applicable and/or maybe related to the reported problem:
- KubeVela version
- K8s cluster version KubeVela is installed on
- Which other K8s CRD controllers used
- Development environment like Go versions, if applicable
#### Enhancement requests
Should explain what enhancement or feature that the author wants to be added and why that is needed.
### Good practices
To make it easier for everyone to understand and find issues they're searching for it's suggested as a general rule of thumbs to:
- Make sure that issue titles are named to explain the subject of the issue, has a correct spelling and doesn't include irrelevant information and/or sensitive information.
- Make sure that issue descriptions doesn't include irrelevant information, information from template that haven't been filled out and/or sensitive information.
- Do your best effort to change title and description or request suggested changes by adding a comment.
> **Note:** Above rules is applicable to both new and existing issues of the KubeVela project.
### Do you have all the information needed to categorize an issue?
Depending on the issue, you might not feel all this information is needed. Use your best judgement.
If you cannot triage an issue using what its author provided, explain kindly to the author that they must provide the
above information to clarify the problem. Label issue with `needs more info` and add any related `area/*` or `type/*` labels.
If the author provides the standard information but you are still unable to triage the issue, request additional information.
Do this kindly and politely because you are asking for more of the author's time.
If the author does not respond to the requested information within the timespan of a week,
close the issue with a kind note stating that the author can request for the issue to be reopened when the necessary information is provided.
When you feel you have all the information needed you're ready to [categorizing the issue](#3-categorizing-an-issue).
If you receive a notification with additional information provided but you are not anymore on issue triage and
you feel you do not have time to handle it, you should delegate it to the current person on issue triage.
## 3. Categorizing an issue
An issue can have multiple of the following labels. Typically, a properly categorized issue should at least have:
- One label identifying its type (`type/*`).
- One or multiple labels identifying the functional areas of interest or component (`area/*`), if applicable.
| Label | Description |
| ------------------------ | ------------------------------------------------------------------------- |
| `type/bug` | A feature isn't working as expected given design or documentation. |
| `type/enhancement` | Request for a new feature or enhancement. |
| `type/docs` | Documentation problem or enhancement. |
| `type/question` | Issue is a question or is perceived as such. |
| `type/duplicate` | An existing issue of the same subject/request have already been reported. |
| `type/wontfix` | A reported bug works as intended/by design. |
| `type/invalid` | A reported bug with invalid usage. |
| `area/*` | Subject is related to a functional area of interest or component. |
### Duplicate issues
Make sure it's not a duplicate by searching existing issues using related terms from the issue title and description.
If you think you know there is an existing issue, but can't find it, please reach out to one of the maintainers and ask for help.
If you identify that the issue is a duplicate of an existing issue:
1. Add a comment `/duplicate of #<issue number>`. GitHub will recognize this and add some additional context to the issue activity.
2. The KubeVela bot will do the rest, adding the correct label and closing comment
3. Optionally add any related `area/*` labels.
### Bug reports
If it's not perfectly clear that it's an actual bug, quickly try to reproduce it.
**It's a bug/it can be reproduced:**
1. Add a comment describing detailed steps for how to reproduce it, if applicable.
2. Label the issue `type/bug` and at least one `area/*` label.
3. If you know that maintainers won't be able to put any resources into it for some time then label the issue
with `help wanted` and optionally `good first issue` together with pointers on which code to update to fix the bug.
This should signal to the community that we would appreciate any help we can get to resolve this.
4. Move on to [prioritizing the issue](#4-prioritization-of-issues).
**It can't be reproduced:**
1. Either [ask for more information](#2-ensure-the-issue-contains-basic-information) needed to investigate it more thoroughly.
2. Either [delegate further investigations](#investigation-of-issues) to someone else.
**It works as intended/by design:**
1. Kindly and politely add a comment explaining briefly why we think it works as intended and close the issue.
2. Label the issue `type/wontfix`.
### Enhancement/feature?
1. Label the issue `type/enhancement` and at least one `area/*` label.
2. Move on to [prioritizing the issue](#4-prioritization-of-issues).
### Documentation issue?
First, evaluate if the documentation makes sense to be included in the KubeVela project:
- Is this something we want/can maintain as a project?
- Is this referring to usage of some specific integration/tool and in that case is that a popular use case in combination with KubeVela?
- If unsure, kindly and politely add a comment explaining that we would need [upvotes](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments)
to identify that lots of other users want/need this.
Second, label the issue `type/docs` and at least one `area/*` label.
**Minor typo/error/lack of information:**
There's a minor typo/error/lack of information that adds a lot of confusion for users and given the amount of work is a big win to make sure fixing it:
1. Either update the documentation yourself and open a pull request.
2. Either delegate the work to someone else by assigning that person to the issue and add the issue to next major/minor milestone.
**Major error/lack of information:**
1. Label the issue with `help wanted` and `good first issue`, if applicable, to signal that we find this important to
fix and we would appreciate any help we can get from the community.
2. Move on to [prioritizing the issue](#4-prioritization-of-issues).
### Support requests and questions
1. Kindly and politely direct the issue author to the [github discussion](https://github.com/oam-dev/kubevela/discussions)
and explain that issue is mainly used for tracking bugs and feature requests.
If possible, it's usually a good idea to add some pointers to the issue author's question.
2. Close the issue and label it with `type/question`.
## 4. Prioritization of issues
In general bugs and enhancement issues should be labeled with a priority.
This is the most difficult thing with triaging issues since it requires a lot of knowledge, context and experience
before being able to think of and start feel comfortable adding a certain priority label.
The key here is asking for help and discuss issues to understand how more experienced project members think and reason.
By doing that you learn more and eventually be more and more comfortable with prioritizing issues.
In case there is an uncertainty around the prioritization of an issue, please ask the maintainers for help.
| Label | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `priority/critical` | Highest priority. Must be actively worked on as someone's top priority right now. |
| `priority/important-soon` | Must be staffed and worked on either currently, or very soon, ideally in time for the next release. |
| `priority/important-longterm` | Important over the long term, but may not be staffed and/or may need multiple releases to complete. |
| `priority/nice-to-have` | It's a good idea, but not scheduled for any release. |
| `priority/awaiting-more-evidence` | Lowest priority. Possibly useful, but not yet enough interest in it. |
| `priority/unscheduled` | Something to look into before and to be discussed during the planning of the next (upcoming) major/minor stable release. |
**Critical bugs**
1. If a bug has been categorized and any of the following criteria apply, the bug should be labeled as critical and
must be actively worked on as someone's top priority right now.
- Results in any crash or data loss.
- Critical security or performance issues
- Problem that makes a feature unusable
- Multiple users experience a severe problem affecting their business, users etc.
2. Label the issue `priority/critical`.
3. Add the issue to the next upcoming patch release milestone. Create a new milestone if there are none.
4. Escalate the problem to the maintainers.
5. Assign or ask a maintainer for help assigning someone to make this issue their top priority right now.
**Important short-term**
1. Label the issue `priority/important-soon`.
2. Add the issue to the next upcoming patch or major/minor stable release milestone. Ask maintainers for help if unsure if it's a patch or not.
Create a new milestone if there are none.
3. Make sure to add the issue to a suitable backlog of a GitHub project and prioritize it or assign someone to work on it now or very soon.
4. Consider requesting [help from the community](#5-requesting-help-from-the-community), even though it may be problematic given a short amount of time until it should be released.
**Important long-term**
1. Label the issue `priority/important-longterm`.
2. Consider requesting [help from the community](#5-requesting-help-from-the-community).
**Nice to have**
1. Label the issue `priority/nice-to-have`.
2. Consider requesting [help from the community](#5-requesting-help-from-the-community).
**Not critical, but unsure?**
1. Label the issue `priority/unscheduled`.
2. Consider requesting [help from the community](#5-requesting-help-from-the-community).
## 5. Requesting help from the community
Depending on the issue and/or priority, it's always a good idea to consider signalling to the community that help from community
is appreciated and needed in case an issue is not prioritized to be worked on by maintainers. Use your best judgement.
In general, requesting help from the community means that a contribution has a good chance of getting accepted and merged.
1. Kindly and politely add a comment to signal to users subscribed to updates of the issue.
- Explain that the issue would be nice to get resolved, but it isn't prioritized to work on by maintainers for an unforeseen future.
- If possible or applicable, try to help contributors getting starting by adding pointers and references to
what code/files need to be changed and/or ideas of a good way to solve/implement the issue.
2. Label the issue with `help wanted`.
3. If applicable, label the issue with `good first issue` to denote that the issue is suitable for a beginner to work on.
4. If possible, try to estimate the amount of work by adding `effort/small`, `effort/medium` or `effort/large`.
## Investigation of issues
When an issue has all basic information provided, but the triage responsible haven't been able to reproduce the reported
problem at a first glance, the issue is labeled [Needs investigation](https://github.com/oam-dev/kubevela/labels/needs%20investigation).
Depending on the perceived severity and/or number of [upvotes](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments),
the investigation will either be delegated to another maintainer for further investigation or put on hold until someone else (maintainer or contributor)
picks it up and eventually starts investigating it.
Investigating issues can be a very time consuming task, especially for the maintainers, provide as much related info will
make it easier for maintainers to investigate.
Even if you don't have the time or knowledge to investigate an issue we highly recommend that you [upvote](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments)
the issue if you happen to have the same problem. If you have further details that may help investigating the issue
please provide as much information as possible.
## Automation
We have some automation that triggers on comments or labels being added to issues.
Many of these automated behaviors are defined in [commands.json](https://github.com/oam-dev/kubevela/blob/main/.github/commands.json).
* Add /duplicate `#<issue number>` to have KubeVela label & close issue with an appropriate message.
* Add `bot/question` and the bot will close it with an appropriate message.
[Read more on bot actions](https://github.com/oam-dev/kubevela/blob/main/.github/bot.md)

8
contribute/README.md Normal file
View 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
View 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
View 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
View 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
View 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.