From 046376aa1a285dda95068d206f8e81ec2e508fc5 Mon Sep 17 00:00:00 2001 From: Jianbo Sun Date: Wed, 16 Jun 2021 20:56:19 +0800 Subject: [PATCH] refine our contributing guides (#1807) * refine our contribute guides * Update CONTRIBUTING.md Co-authored-by: Hongchao Deng Co-authored-by: Hongchao Deng --- .github/ISSUE_TEMPLATE/bug_report.md | 12 +- CONTRIBUTING.md | 214 +++--------------- ISSUE_TRIAGE.md | 323 +++++++++++++++++++++++++++ contribute/README.md | 8 + contribute/coding-conventions.md | 162 ++++++++++++++ contribute/create-pull-request.md | 86 +++++++ contribute/developer-guide.md | 145 ++++++++++++ contribute/triage-issues.md | 40 ++++ 8 files changed, 808 insertions(+), 182 deletions(-) create mode 100644 ISSUE_TRIAGE.md create mode 100644 contribute/README.md create mode 100644 contribute/coding-conventions.md create mode 100644 contribute/create-pull-request.md create mode 100644 contribute/developer-guide.md create mode 100644 contribute/triage-issues.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 2d4e669ee..d92ae81d4 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -15,9 +15,9 @@ A clear and concise description of what the bug is. **To Reproduce** @@ -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** + + + **Cluster information** +``` + +-----------------------------+ + | | + | 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 #`. 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 `#` 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) diff --git a/contribute/README.md b/contribute/README.md new file mode 100644 index 000000000..ffdd0fb5d --- /dev/null +++ b/contribute/README.md @@ -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) diff --git a/contribute/coding-conventions.md b/contribute/coding-conventions.md new file mode 100644 index 000000000..61e72652d --- /dev/null +++ b/contribute/coding-conventions.md @@ -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. \ No newline at end of file diff --git a/contribute/create-pull-request.md b/contribute/create-pull-request.md new file mode 100644 index 000000000..82ff0ad70 --- /dev/null +++ b/contribute/create-pull-request.md @@ -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 #` or `Fixes #`. +- 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). diff --git a/contribute/developer-guide.md b/contribute/developer-guide.md new file mode 100644 index 000000000..a249cfc87 --- /dev/null +++ b/contribute/developer-guide.md @@ -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+ + +
+ Install Kubebuilder manually + +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 +``` + +
+ +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) diff --git a/contribute/triage-issues.md b/contribute/triage-issues.md new file mode 100644 index 000000000..87a8a50d2 --- /dev/null +++ b/contribute/triage-issues.md @@ -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 (`#`) to the other. +Explain why you think the issue is duplicated.