From c590fe264083a58c1b372b664dd92eb0d0843cb2 Mon Sep 17 00:00:00 2001 From: adohe Date: Mon, 10 Jun 2024 16:29:53 +0800 Subject: [PATCH] docs: update contributing guide --- docs/CODE_OF_CONDUCT.md => CODE_OF_CONDUCT.md | 0 CONTRIBUTING.md | 88 +++++++++++++++ docs/contributing.md | 101 ------------------ 3 files changed, 88 insertions(+), 101 deletions(-) rename docs/CODE_OF_CONDUCT.md => CODE_OF_CONDUCT.md (100%) create mode 100644 CONTRIBUTING.md delete mode 100644 docs/contributing.md diff --git a/docs/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md similarity index 100% rename from docs/CODE_OF_CONDUCT.md rename to CODE_OF_CONDUCT.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..970360e3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ +# Contributing + +Welcome to Kusion! + +We warmly appreciate your talent and creativity in contributing to this project. This guide will help direct you to the best places to start contributing. Follow the instructions below, you'll be able to pick up issues, write code to fix them, and get your work reviewed and merged. + +Feel free to create issues and contribute your code. Whether you are an experienced developer or just beginning your journey in the open-source world, we highly encourage your participation. + +If you have any questions or need further information, please don't hesitate to contact us. + +--- + +- [Before you get started](#before-you-get-started) + - [Code of Conduct](#code-of-conduct) + - [Community Expectations](#community-expectations) +- [Getting started](#getting-started) +- [Your First Contribution](#your-first-contribution) + - [Find something to work on](#find-something-to-work-on) + - [Find a good first topic](#find-a-good-first-topic) + - [Work on an Issue](#work-on-an-issue) +- [Contributor Workflow](#contributor-workflow) + - [Creating Pull Requests](#creating-pull-requests) + - [Code Review](#code-review) + - [Testing](#testing) + +# Before you get started + +## Code of Conduct + +Please make sure to read our [Code of Conduct](/CODE_OF_CONDUCT.md). + +## Community Expectations + +Kusion is an open source project driven by its community which strives to promote a healthy, friendly and productive environment. Kusion aims to simplify the process of deploying applications into your infrastructure and helps you standardize your deployment process. + +# Getting started + +- Fork the repository on GitHub. +- Make your changes on your fork repository. +- Submit a PR. + +# Your First Contribution + +We will help you to contribute in different areas like filing issues, developing features, fixing critical bugs and getting your work reviewed and merged. + +If you have questions about the development process, feel free to [file an issue](https://github.com/KusionStack/kusion/issues/new/choose). + +## Find something to work on + +We are always in need of help, be it fixing documentation, reporting bugs or writing some code. +Look at places where you feel best coding practices aren't followed, code refactoring is needed or tests are missing. Here is how you get started. + +### Find a good first issue + +[Kusion](https://github.com/KusionStack/kusion) has [help wanted](https://github.com/KusionStack/kusion/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) and [good first issue](https://github.com/KusionStack/kusion/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) labels for issues that should not need deep knowledge of the system. We can help new contributors who wish to work on such issues. + +Another good way to contribute is to find a documentation improvement, such as a missing/broken link. +Please see [Contributing](#contributing) below for the workflow. + +#### Work on an issue + +When you are willing to take on an issue, just reply on the issue. The maintainer will assign it to you. + +# Contributor Workflow + +Please do not ever hesitate to ask a question or send a pull request. + +This is a rough outline of what a contributor's workflow looks like: + +- Create a topic branch from where to base the contribution. This is usually master. +- Make commits of logical units. +- Push changes in a topic branch to a personal fork of the repository. +- Submit a pull request to [Kusion](https://github.com/KusionStack/kusion). + +## Creating Pull Requests + +Pull requests are often called simply "PR". Kusion generally follows the standard [github pull request](https://help.github.com/articles/about-pull-requests/) process. To submit a proposed change, please develop the code/fix and add new test cases. After that, run these local verifications before submitting pull request to predict the pass or fail of continuous integration. + +* Run and pass `make lint` +* Run and pass `make test` + +## Code Review + +To make it easier for your PR to receive reviews, consider the reviewers will need you to: + +* follow [good coding guidelines](https://github.com/golang/go/wiki/CodeReviewComments). +* write [good commit messages](https://chris.beams.io/posts/git-commit/). +* break large changes into a logical series of smaller patches which individually make easily understandable changes, and in aggregate solve a broader issue. diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index 7a0a2d71..00000000 --- a/docs/contributing.md +++ /dev/null @@ -1,101 +0,0 @@ -# Contributing to Kusion - -Welcome to Kusion! Kusion is the cloud-native platform engineering engine of [KusionStack](https://github.com/KusionStack). - -We warmly appreciate your talent and creativity in contributing to this project. This guide will help direct you to the best places to start contributing. Follow the instructions below, you'll be able to pick up issues, write code to fix them, and get your work reviewed and merged. - -Feel free to create issues and contribute your code. Whether you are an experienced developer or just beginning your journey in the open-source world, we highly encourage your participation. - -If you have any questions or need further information, please don't hesitate to contact us. - ---- - -- [Contributing to Kusion](#contributing-to-kusion) - - [File an Issue](#file-an-issue) - - [Contribute a Pull Request](#contribute-a-pull-request) - - [Fork Repository](#fork-repository) - - [Develop Code](#develop-code) - - [Open a Pull Request](#open-a-pull-request) - - [Sign CLA](#sign-cla) - - [PR Checks](#pr-checks) - -## File an Issue - -The first step to start contributing to Kusion is to find something to work on. Help is always welcome, and no contribution is too small! - -Here are some things you can do today to get started contributing: - -* Help improve the Kusion documentation -* Clarify code, variables, or functions that can be renamed or commented on -* Write test coverage -* Help triage issues - -We use [issues](https://github.com/KusionStack/kusion/issues) to track tasks. Choose an existing issue with the label `good first issue` or `help wanted` is a good choice, or you can open a new issue. Now, Kusion provides three issue templates as follows, please choose one according to your need: - -* Bug Report: Report a bug encountered while operating Kusion -* Enhancement Tracking Issue: Provide supporting details for a feature in development -* Failing Test: Report continuously failing tests or jobs in Kusion CI - -In the issue, please describe your problem clearly and accurately, and choose a label to define the issue's type. There are the commonly used labels: - -* area/cli: Categorizes an issue or PR as relevant to CLI -* area/engine: Categorizes an issue or PR as relevant to Kusion engine -* area/release: Categorizes an issue or PR as relevant to releasing -* area/runtime: All Infrastructure Runtime, eg: k8s -* area/testing: Categorizes an issue or PR as relevant to testing -* kind/feature: Categorizes an issue or PR as relevant to a new feature - -## Contribute a Pull Request - -After opening an issue, you could contribute codes to Kusion by a pull request. Here are the steps you should follow: - -### Fork Repository - -Kusion adopts trunk-based development, i.e., the code used for release is maintained on the main branch. And to keep the repository tidy, Kusion only has the main branch. - -Thus, to develop Kusion, you have to fork the [KusionStack/kusion](https://github.com/KusionStack/kusion) repository to your workspace, and then check out a new branch to develop coding. - -### Develop Code - -Now you can start coding to solve the issue. To maintain the code quality of Kusion, unit tests are indispensable for the functions you added or updated. - -After the development is completed, commit and push to your own forked repository. Cause the code will merge into Kusion repository by pull request, [commitlint/[config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) should be followed, the legal prefixes for the commit message are shown below: - -* build -* chore -* ci -* docs -* feat -* fix -* perf -* refactor -* revert -* style -* test - -### Open a Pull Request - -[Open a pull request](https://github.com/KusionStack/kusion/pulls) from the develop branch of your forked repository to the main branch of Kusion. You should clearly describe what you do in the PR, and link it to an issue. Besides, the PR title should also follow the commit conventions described above, and must be 5-256 characters in length, prefix `WIP` and `[WIP]` are not allowed. - -### Sign CLA - -If it was your first pull request, you need to sign our [CLA(Contributor License Agreement)](https://github.com/KusionStack/.github/blob/main/CLA.md). The only thing you need to do is to post a pull request comment same as the below format: - -`I have read the CLA Document and I hereby sign the CLA` - -If your CLA signature failed, you may find the solutions below: - -* The comment must be in exactly the same format as above, with no extra spaces, line breaks, etc. -* The git committer must be the same one who created the Kusion PR - -### PR Checks - -To keep the reliability of the Kusion project, the following check will get triggered automatically: - -* Unit Test -* E2E Test -* Golang Lint -* Commit Lint -* PR Title lint - -Please make sure your PR passes these checks.