diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..bcc9a8c --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,3 @@ +# KusionStack Community Code of Conduct + +KusionStack follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d87132..f25bc5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,487 +1,99 @@ -# Contribute to the KusionStack project +# Contributing to KusionStack -* [Pull requests](#pull-requests) -* [GitHub basic setup](#github-basic-setup) - * [Prerequisites](#prerequisites) - * [Contributor roles](#contributor-roles) - * [Golang coding style](#golang-coding-style) - * [Rust coding style](#rust-coding-style) -* [GitHub best practices](#github-best-practices) - * [Submit issues before PRs](#submit-issues-before-prs) - * [Issue tracking](#issue-tracking) - * [Closing issues](#closing-issues) -* [GitHub workflow](#github-workflow) - * [Configure your environment](#configure-your-environment) -* [Patch format](#patch-format) - * [General format](#general-format) - * [Best practices for patches](#best-practices-for-patches) - * [Examples](#examples) -* [Reviews](#reviews) - * [Review Examples](#review-examples) -* [Continuous Integration](#continuous-integration) -* [Contact](#contact) -* [Project maintainers](#project-maintainers) +Welcome to KusionStack! KusionStack is a technology stack for building cloud-native Internal Developer Platforms. -The KusionStack project is an open source project licensed under the -[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). +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. -It comprises a number of repositories under the [GitHub KusionStack organization](https://github.com/KusionStack). Unless -explicitly stated otherwise, all the KusionStack repositories follow the -process documented here. +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. -## Pull requests +If you have any questions or need further information, please don't hesitate to contact us. -All the repositories accept contributions via [GitHub Pull requests (PR)](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests). Submit PRs by following the [GitHub workflow](#github-workflow). +--- -## GitHub basic setup +- [Contributing to KusionStack](#contributing-to-kusionstack) + - [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) -To get started, complete the prerequisites below. +## File an Issue -### Prerequisites +The first step to start contributing to KusionStack is to find something to work on. Help is always welcome, and no contribution is too small! -- Review [Contributor roles](#contributor-roles) that require special Git - configuration. +Here are some things you can do today to get started contributing: -- [Set up Git](https://help.github.com/en/github/getting-started-with-github/set-up-git). - - >**Note:** The email address you specify must match the email address you - >use to sign-off commits. +* Help improve the KusionStack documentation +* Clarify code, variables, or functions that can be renamed or commented on +* Write test coverage +* Help triage issues -- [Fork and Clone](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) the relevant repository at the - [KusionStack Project](https://github.com/KusionStack). +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, KusionStack provides three issue templates as follows, please choose one according to your need: - Example: Your local clone should show `your-github-username`, as follows. - `https://github.com/${your-github-username}/community`. +* Bug Report: Report a bug encountered while operating KusionStack +* Enhancement Tracking Issue: Provide supporting details for a feature in development +* Failing Test: Report continuously failing tests or jobs in KusionStack CI -### Contributor roles +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: -Special Git configuration is required for these contributors: +* area/release: Categorizes an issue or PR as relevant to releasing +* area/testing: Categorizes an issue or PR as relevant to testing +* kind/feature: Categorizes an issue or PR as related to a feature +* kind/bug: Categorizes an issue or PR as related to a bug -* [Golang coding style](#golang-coding-style) -* [Rust coding style](#rust-coding-style) +## Contribute a Pull Request -For all other contributor roles, follow the standard configuration, shown in -Prerequisites. +After opening an issue, you could contribute codes to KusionStack by a pull request. Here are the steps you should follow: -### Golang coding style +### Fork Repository -* Review [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) to avoid common `Golang` errors. -* Use `gofmt` to fix any mechanical style issues. +KusionStack adopts trunk-based development, i.e., the code used for release is maintained on the main branch. To keep the repository tidy, All projects in KusionStack only have the main branch. -### Rust coding style +Thus, to develop KusionStack, you have to fork one project in [KusionStack](https://github.com/KusionStack/) repository to your workspace, and then check out a new branch to develop coding. -* Use `rustfmt` to fix any mechanical style issues. Rustfmt uses a style which conforms to the -[Rust Style Guide](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md). -* Use `clippy` to catch common mistakes and improve your Rust code. +### Develop Code -You can install the above tools as follows. +Now you can start coding to solve the issue. To maintain the code quality of KusionStack, unit tests are indispensable for the functions you added or updated. -```sh -$ rustup component add rustfmt clippy -``` +After the development is completed, commit and push to your forked repository. Cause the code will merge into one KusionStack 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: -## GitHub best practices +* build +* chore +* ci +* docs +* feat +* fix +* perf +* refactor +* revert +* style +* test -### Submit issues before PRs +### Open a Pull Request -Raise a GitHub issue **before** starting work on a PR. +[Open a pull request](https://github.com/KusionStack/kusion/pulls) from the develop branch of your forked repository to the main branch of KusionStack. 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. -* Our process requires an issue to be associated with every PR (see [patch format](#patch-format)) +### Sign CLA -* If you are a new contributor, create an issue and add a comment stating -that you intend to work on the issue. This notifies our team of the work you -plan to do. +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: -### Issue tracking +`I have read the CLA Document and I hereby sign the CLA` -To report a bug that is not already documented, please open a GitHub issue for the repository in question. +If your CLA signature failed, you may find the solutions below: -If it is unclear which repository to raise your query against, first try to -get in [contact](#contact) with us. If in doubt, raise the issue -[here](https://github.com/KusionStack/community/issues/new) and we will -help you to handle the query by routing it to the correct area for resolution. +* The comment must be in the same format as above, with no extra spaces, line breaks, etc. +* The git committer must be the same one who created the KusionStack PR -### Closing issues +### PR Checks -Our tooling requires adding a `Fixes` comment to at least one commit in the PR, which triggers GitHub to automatically close the issue once the PR is merged: +To keep the reliability of the KusionStack project, the following check will get triggered automatically: -``` -pod: Remove token from Cmd structure - -The token and pid data will be hold by the new Process structure and -they are related to a container. - -Fixes #123 - -Signed-off-by: Name -``` - -The issue is automatically closed by GitHub when the -[commit message](https://help.github.com/articles/closing-issues-via-commit-messages/) is parsed. - -## GitHub workflow - -KusionStack employs certain augmentations to a -[standard GitHub workflow](https://guides.github.com/introduction/flow/). -In this section, we explain these augmentations in more detail. Follow these guidelines when contributing to KusionStack repositories, except where noted below. - -* Complete the [GitHub basic setup](#github-basic-setup) above before continuing. - -* Ensure each PR only covers one topic. If you mix up different items in - your patches or PR, they will likely need to be reworked. - -* Follow a [topic branch method](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-branches) for development. - -* Follow carefully the [patch format](#patch-format) for PRs. - -* Apply the appropriate GitHub labels to your PR. This - is particularly relevant to maintain [Stable branch backports](#stable-branch-backports). - - >**Note:** External contributors should use keywords, explained in the - >link above. Labels may not be visible to external contributors. - -* [Rebase](https://help.github.com/en/github/using-git/about-git-rebase) - commits on your branch and `force push` after each cycle of feedback. - -### Configure your environment - -Most [KusionStack repositories](https://github.com/KusionStack) -contain code written in the [Go language (golang)](https://golang.org) and [Rust language](https://www.rust-lang.org/). Please install Go 1.17+ and Rust 1.60 stable. - -#### Fork and clone - -In this example, we configure a Git environment to contribute to this very -`Community` repo. We create a sample branch, incorporate reviewer feedback, and rebase our commits. - -1. Fork the [upstream repository](https://help.github.com/articles/cloning-a-repository): - -1. [Clone your forked copy of the upstream repository](https://help.github.com/articles/cloning-a-repository): - -1. While on your *forked copy*, select the green button `Clone or download` - and copy the URL. - -1. Run the commands below and **paste the copied URL** (previous step), - so your real GitHub user name replaces `your-github-username` below. - -```sh -$ dir="$GOPATH/src/github.com/KusionStack" -$ mkdir -p "$dir" -$ cd "$dir" -$ git clone https://github.com/{your-github-username}/community -$ cd community -``` - ->**Note:** Cloning a forked repository automatically gives a remote `origin`. - -#### Configure the upstream remote - -Next, add the remote `upstream`. Configuring this remote allows you to -synchronize your forked copy, `origin`, with the `upstream`. The -`upstream` URL varies by repository. We use the `upstream` from the Community for this example. - -1. Change directory into `community`. - -1. Set the remote `upstream` as follows. - - ```sh - $ git remote add upstream https://github.com/KusionStack/community - ``` - -1. Run `git remote -v`. Your remotes should appear similar to these: - - ``` - origin https://github.com/your-github-username/community.git (fetch) - origin https://github.com/your-github-username/community.git (push) - upstream https://github.com/KusionStack/community (fetch) - upstream https://github.com/KusionStack/community (push) - ``` - -For more details, see how to [set up a git remote](https://help.github.com/articles/configuring-a-remote-for-a-fork). - -#### Create a topic branch - -1. Create a new "topic branch" to do your work on: - - ``` - $ git checkout -b fix-contrib-bugs - ``` - - >**Warning:** *Never* make changes directly to the `master` branch - >--*always* create a new "topic branch" for PR work. - -1. Make some editorial changes. In this example, we modify the file that - you are reading. - - ``` - $ $EDITOR CONTRIBUTING.md - ``` - - >**Note:** If editing in Windows make sure that all documents end with LF - > and not CRLF. The CI system will fail if carriage returns are in the - > document. Many editors support the ability to change this. There is a - > tool called dos2unix available on Git Bash for Windows and also available - > on Linux systems that can convert files to LF endings. See the - > [Configuring Git to handle line endings](https://docs.github.com/en/github/getting-started-with-github/getting-started-with-git/configuring-git-to-handle-line-endings) - > guide for more details on how to configure `git` to automatically insert - > the correct line endings. - -1. Commit your changes to the current (`fix-contrib-bugs`) branch. Assure - you use the correct [patch format](#patch-format): - - ``` - $ git commit -as - ``` - -1. Push your local `fix-contrib-bugs` branch to your remote fork: - - ``` - $ git push -u origin fix-contrib-bugs - ``` - - >**Note:** The `-u` option tells `git` to "link" your local clone with - > your remote fork so that it knows from now on that the local repository - > and the remote fork refer to "the same" upstream repository. Strictly - >speaking, this option is only required the first time you call `git push` - >for a new clone. - -1. Create the PR: - - Browse to https://github.com/KusionStack/community. - - Click the "Compare & pull request" button that appears. - - Click the "Create pull request" button. - - >**Note:** You do not need to change any of the defaults on this page. - -#### Update your PR based on review comments - -Suppose you received some reviewer feedback that asked you to make some -changes to your PR. You updated your local branch and committed those -review changes by creating three commits. There are now four commits in your -local branch: the original commit you created for the PR and three other -commits you created to apply the review changes to your branch. Your branch -now looks something like this: - -```sh -$ git log master.. --oneline --decorate=no -4928d57 docs: Fix typos and fold long lines -829c6c8 apply review feedback changes -7c9b1b2 remove blank lines -60e2b2b doh - missed one -``` - ->**Note:** The `git log` command compares your current branch ->(`fix-contrib-bugs`) with the `master` branch and lists all the commits, ->one per line. - -#### Git rebase if multiple commits - -Since all four commits are related to *the same change*, it makes sense to -combine all four commits into a *single commit* on your PR. You need to -[git rebase](https://help.github.com/github/using-git/about-git-rebase) -multiple commits on your branch. Follow these steps. - -1. Update the `master` branch in your local copy of the upstream - repository: - - ``` - $ cd $GOPATH/src/github.com/KusionStack/community - $ git checkout master - $ git pull --rebase upstream master - ``` - - The previous command downloads all the latest changes from the upstream - repository and adds them to your *local copy*. - -1. Now, switch back to your PR branch: - - ``` - $ git checkout fix-contrib-bugs - ``` - -1. Rebase your changes against the `master` branch. - - ```sh - $ git rebase -i master - ``` - - Example output: - - ```sh - pick 2e335ac docs: Fix typos and fold long lines - pick 6d6deb0 apply review feedback changes - pick 23bc01d remove blank lines - pick 3a4ba3f doh - missed one - ``` - -1. In your editor, read the comments at the bottom of the screen. - Do not modify the first line, `pick 2e335ac docs: Fix typos ...`. Instead, revise `pick` to `squash` at the start of all following lines. - - Example output: - - ```sh - pick 2e335ac docs: Fix typos and fold long lines - squash 6d6deb0 apply review feedback changes - squash 23bc01d remove blank lines - squash 3a4ba3f doh - missed one - ``` - -1. Save your changes and quit the editor. Git puts you *back* into your - editor. You will see all the commit *messages*. - -1. At top is your first commit, which should be in the - [correct format](#patch-format). Keep your first commit and delete - all the following commits, as appropriate, based on - the review feedback. - -1. Save the file and quit the editor. Once this operation completes, the four - commits will have been converted into a single new commit. Check this by - running the `git log` command again: - - ```sh - $ git log master.. --oneline --decorate=no - 3ea3aef docs: Fix typo - ``` - -1. Force push your updated local `fix-contrib-bugs` branch to `origin` - remote: - - ```sh - $ git push -f origin fix-contrib-bugs - ``` - ->**Note:** Not only does this command upload your changes to your fork, it ->also includes the *latest upstream changes* to your fork since you ran ->`git pull --rebase upstream master` on the master branch and then merged ->those changes into your PR branch. This ensures your fork is now "up to ->date" with the upstream repository. The `-f` option is a "force push". Since ->you created a new commit using `git rebase`, you must "overwrite" the old ->copy of your branch in your fork on GitHub. - -Your PR is now updated on GitHub. To ensure team members are aware of this, -leave a message on the PR stating something like, "Review feedback applied". -This notification allows the team to once again review your PR more quickly. - -## Patch format - -### General format - -Beside the `Signed-off-by` footer, we expect each patch to comply with the -following format: - -``` -subsystem: One line change summary - -More detailed explanation of your changes (why and how) -that spans as many lines as required. - -A "Fixes #issue-id" comment listing the GitHub issue this change resolves. -This comment is required for the main patch in a sequence. See the following examples. - -Signed-off-by: Contributors Name -``` - -### Best practices for patches - -We recommend that each patch fixes one thing. Smaller patches are easier to -review, more likely to be accepted and merged, and more conducive for -identifying problems during review. - -A PR can contain multiple patches. These patches should generally be related -to the [main patch](#main-patch) and the overall goal of the PR. However, it -is also acceptable to include additional or -[supplementary patches](#supplementary-patch) for things such as: - -- Formatting (or whitespace) fixes -- Comment improvements -- Tidy up work -- Refactoring to simplify the codebase - -### Examples - -#### Main patch - -The following is an example of a full patch description for the main change that shows the required "`Fixes #issue-id`" comment, which references the GitHub issue this patch resolves: - -``` -pod: Remove token from Cmd structure - -The token and pid data will be hold by the new Process structure and -they are related to a container. - -Fixes: #123 - -Signed-off-by: Name -``` - -#### Supplementary patch - -If a PR contains multiple patches, [only one of those patches](#main-patch) needs to specify the "`Fixes #issue-id`" comment. Supplementary patches have an identical format to the main patch, but do not need to specify a "`Fixes #issue-id`" -comment. - -Example: - -``` -image-builder: Fix incorrect error message - -Fixed an error message which was referring to an incorrect rootfs -variable name. - -Signed-off-by: Name -``` - -## Reviews - -Before your PRs are merged into the main code base, they are reviewed. We -encourage anybody to review any PR and leave feedback. - -See the [PR review guide](PR-Review-Guide.md) for tips on performing a -careful review. - -We use the GitHub [Required Reviews](https://help.github.com/articles/approving-a-pull-request-with-required-reviews/) -system for reviewers to note if they agree or disagree with a PR. To have -an acknowledgment or "nack" registered with GitHub, you **must** use the -GitHub "Review changes" dialog to leave feedback. Notes left only in the -comments fields, whilst sometimes useful, will not get registered -in the acknowledgment counting system. - -Documentation PRs can sometimes use a modified process explained in the -[Documentation Review Process](Documentation-Review-Process.md) guide. - -### Review Examples - -The following is an example of a valid "ack", as long as -the "Approve" box is ticked in the Review changes dialog: - -``` -Excellent work - thanks for your contribution. - -lgtm -``` - -## Continuous Integration - -The KusionStack project has a gating process to prevent introducing -regressions. When your PR is submitted, a Continuous Integration (CI) system -will run different checks on different platforms, based upon your changes. - -All CI jobs must pass in order to merge your PR. - -## Contact - -The KusionStack community can be reached -[through various channels](README.md#join-us). - -## Project maintainers - -The KusionStack project maintainers are the people accepting or -rejecting any PR. Although [anyone can review PRs](#reviews), only the -acknowledgement (or "ack") from an Approver counts towards the approval of a PR. - -Approvers are listed in GitHub teams, one for each repository. The project -uses the -[GitHub required status checks](https://help.github.com/en/articles/enabling-required-status-checks) -along with the [GitHub `CODEOWNERS`file](https://help.github.com/en/articles/about-code-owners) to specify who can approve PRs. All repositories are configured to require: - -- Two approvals from the repository-specific approval team. - -- One [documentation team](https://github.com/orgs/KusionStack/teams/documentation/members) approval if the PR modifies documentation. +* Unit Test +* E2E Test +* Golang Lint +* Commit Lint +* PR Title lint +Please make sure your PR passes these checks. \ No newline at end of file diff --git a/Documentation-Review-Process.md b/Documentation-Review-Process.md deleted file mode 100644 index 4037da0..0000000 --- a/Documentation-Review-Process.md +++ /dev/null @@ -1,161 +0,0 @@ -# Documentation review process - -* [Introduction](#introduction) -* [The Documentation Team](#the-documentation-team) -* [Default document review process](#default-document-review-process) -* [Justification for different process](#justification-for-different-process) - * [Users should always expect accurate Documentation](#users-should-always-expect-accurate-documentation) - * [Some documentation PRs can be fast-tracked](#some-documentation-prs-can-be-fast-tracked) - * [Formal doc reviews can be very time-intensive](#formal-doc-reviews-can-be-very-time-intensive) -* [Decision Authority](#decision-authority) -* [Determine if a full document review is required](#determine-if-a-full-document-review-is-required) - * [Exempt](#exempt) - * [Required](#required) -* [Requesting a formal document review](#requesting-a-formal-document-review) -* [Lightweight document review process](#lightweight-document-review-process) - -## Introduction - -The process for reviewing documentation PRs is slightly different from -[the general process for reviewing code PRs](https://github.com/KusionStack/community/blob/master/CONTRIBUTING.md#reviewsPR-Review-Guide.md). -This document explains the differences. - -## The Documentation Team - -The Documentation Team is responsible for carrying out a full documentation -review of a PRs containing documentation changes. Such a review includes -checking the grammar, structure, consistency, and typographical correctness of -the documentation changes. - -The following GitHub team lists the users who are members of the Documentation Team: - -- https://github.com/orgs/KusionStack/teams/documentation/members - -## Default document review process - -[Project maintainers](https://github.com/KusionStack/community/blob/master/CONTRIBUTING.md#project-maintainers) -have the power to approve or reject PRs. - -If a Documentation Team review is required, the `CODEOWNERS` configuration will -apply and the PR will be blocked until the required number of acks are -obtained for the documentation changes. - -Technical writers from the Documentation Team will review the document -changes and add comments explaining how the wording should be changed. It is -then up to the PR creator to apply these changes to their original PR, -rebasing as necessary to ensure a clean `git(1)` history. Once the creator has -applied the changes they need to re-push their branch and add a comment to the -PR asking for a re-review. This process continues indefinitely until the the -Documentation Team is happy with the final result. - -## Justification for different process - -The documentation review process is different than the code review process for -the following reasons: - -### Users should always expect accurate Documentation - -Just like code changes, some documentation changes have to be merged as soon -as possible to ensure users have current and accurate information. - -Documentation changes tend to be more urgent though. For example, a "Priority -1" code issue needs to be fixed quickly. However it would also need to be -documented clearly (and quickly). If the P1 issue *cannot* be fixed quickly, -the documentation must still be updated as soon as possible to alert users of -the issue and to provide suitable workarounds. - -If the documentation is *not* kept current, users have incorrect information -and might create problems for themselves or become disaffected with the -project entirely. - -In summary, do not let documentation PRs sit in the PR backlog for any longer -than necessary. - -### Some documentation PRs can be fast-tracked - -If a PR makes a minor change to one or more documents, passing to the -Documentation Team for a formal review and approval might not be necessary. - -### Formal doc reviews can be very time-intensive - -Since a full document review can be a slow and pain-staking process, and since -the number of professional technical writers on the Documentation Team is -relatively small compared to the number of developers, it makes sense to only -perform such reviews on the documents that justify the effort. - -## Decision Authority - -If a Documentation Team member believes a full review is required, their -decision is final. - -In most other cases, a project maintainer will decide whether a full review is -required or not. - -If project maintainers cannot decide whether the lightweight process should be -followed, the full process should be used instead since the uncertainty -implies "more eyes" should see the changes. - -## Determine if a full document review is required - -### Exempt - -If a PR contains documentation changes that **only** relate to one or more of -the following categories, it does not need to be formally reviewed and -approved by the Documentation Team: - -- Changes to code blocks - - The PR only modifies code blocks embedded in the document. - -- "Typo" fixes - - The PR only fixes spelling mistakes and whitespace issues. - -- Formatting - - The PR only modifies the layout of the existing text. For example, you - update words to render them in a ``fixed font`` to fit the standard formatting conventions. - -- URL fixes - - The PR only modifies URLs or updates the table of contents. - -- The PR only *removes* documentation. - -### Required - -The following PR changes generally indicate a full document review is -necessary: - -- A new document has been added by the PR. - - All documents should have an initial review unless they are extremely simple. - -## Requesting a formal document review - -If a PR needs a full document review, add a comment to the PR like the -following, which sends a mail to all members of the Documentation Team: - -``` -PTAL @KusionStack/documentation -``` - -## Lightweight document review process - -1. Obtain general agreement that - a Document Team review [is not required](#decision-authority). - -1. Ensure all other approvals and CI checks have been met. - -1. Ensure the PR contains a note explaining why the PR does not justify a full review. - -1. Request a project maintainer force-merges the PR. - - This operation bypasses the check that normally stops a PR from - landing until the Documentation Team acks the PR. - -1. The maintainer should notify the Documentation Team out of courtesy that - the PR has been merged. - - This allows a follow-on "recovery PR" to be raised should the Documentation - Team disagree on using the lightweight process. \ No newline at end of file diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..513d2c4 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,14 @@ +# KusionStack Maintainers + +The following is the list of maintainers for all KusionStack repositories, in alphabetical order: + +- Dayuan Li [@SparkYuan](https://github.com/SparkYuan) +- Haoming Liu [@liu-hm19](https://github.com/liu-hm19) +- Jun Zhang [@zoumo](https://github.com/zoumo) +- Ke Wu [@wu8685](https://github.com/wu8685) +- Shuai Pan [@panshuai-ps](https://github.com/panshuai-ps) +- Yankang Ji [@healthjyk](https://github.com/healthjyk) +- Yingming Yang [@elliotxx](https://github.com/elliotxx) +- Yikun Wang [@Eikykun](https://github.com/Eikykun) +- Zai Chen [@ffforest](https://github.com/ffforest) +- Zibo He [@adohe](https://github.com/adohe) \ No newline at end of file diff --git a/PR-Review-Guide.md b/PR-Review-Guide.md deleted file mode 100644 index 973d61a..0000000 --- a/PR-Review-Guide.md +++ /dev/null @@ -1,136 +0,0 @@ -* [High level considerations](#high-level-considerations) - * [Security](#security) - * [Reliability](#reliability) - * [Performance](#performance) - * [Maintenance](#maintenance) - * [Usability](#usability) -* [Specifics to consider](#specifics-to-consider) - * [Basics](#basics) - * [Layout and formatting](#layout-and-formatting) - * [Design](#design) - * [Code comments](#code-comments) - * [Documentation](#documentation) - * [Logging and debugging](#logging-and-debugging) - * [Testing](#testing) - * [Environments](#environments) - * [Upgrades](#upgrades) -* [Mandatory checks](#mandatory-checks) - ---- - -This document attempts to capture some of the points to consider when -reviewing a [new code contribution](CONTRIBUTING.md) (a Pull Request (PR)) to -ensure overall quality is high. - -## High level considerations - -### Security - -- Does the change introduce a potential security risk? - - What additional checks resolve the potential security risk? - -### Reliability - -- What happens on failure? Consider **every** possible failure. For example: - - Are temporary files left on the disk? - - Are any resources (e.g. memory and open files) leaked? - -- If the code crashes, what is the overall system impact? - - Can the system be restarted and recovered? - - Is [security](#security) compromised? - -### Performance - -- Does this change negatively impact performance? -- Can any calls block? If yes, there must be a log call before the blocking call explaining what is about to be done. - -### Maintenance - -- How easy is this code to maintain: - - By an experienced developer on the project? - - By a developer with none or almost no experience of the code base or the project? - -### Usability - -- Does the change improve usability or make it worse? -- Can usability be improved further? - -## Specifics to consider - -### Basics - -- Consider *all* inputs and outputs. -- What resources are being used (e.g. memory, disk, etc.)? Are the resources released? -- Are all return values and arguments checked? -- Are there any magic numbers? - -### Layout and formatting - -- Is formatting and naming consistent? -- Are there any spelling mistakes ("typos")? -- Do all new files contain the required licence header? - -### Design - -- Can the code be simplified or refactored? - - Is the code "too clever"? Overly clever code can be fragile. Reject it unless there is a **very** good documented reason. -- Is there a better (simpler) solution to the problem? -- Is there any duplication? -- Does the code "reinvent the wheel?" Is there a standard package you can use instead? -- What assumptions does the code make? Are the assumptions valid and documented? -- Does the code make sense? - - Someone with minimal exposure to the codebase should be able to guess what the code is doing. - -### Code comments - -- Is the code well commented? -- Are all functions and function parameters documented. For `golang` programs, is their purpose obvious? -- Does this change require an update to the README(s) or architecture docs, installation docs, or limitations docs? -- Are any lines commented out? If yes, remove them. -- Are there any `FIXME` or `TODO`'s? If yes, replace them with a full URL to an issue number tracking the work to be done. - -### Documentation - -- Should the document update be applied to any *other* documents? - For example, when a PR updates an installation guide, determine whether those changes apply to one or more of the other installation guides. -- Does the PR make any of the following changes? If yes, determine if a documentation change is necessary: - - New programs or scripts are added or removed. - - New program or script options are added or removed. - - New config options are added or removed. - - New features are added or removed. - - Existing bug(s) are fixed. - -### Logging and debugging - -- Can someone debug this code from a logfile if it fails? -- Are all fatal scenarios logged? -- Are error messages and log calls useful and comprehensive? Ensure sensitive information is **not** displayed. - -### Testing - -- Is the code easy to test? -- Are there new unit tests? If not, why not? -- What other classes of testing (e.g. integration, system, stress, fuzz) can someone write to check the code? - -### Environments - -- Does the code work on all distributions? -- Does the code work on all architectures? -- What environments does your code run in? -- Which user does the code run as? If it runs as the superuser, have clear documentation to explain why this is necessary. - -### Upgrades - -- If the code logs internal state to a file or shared memory, how are upgrades handled? -For example, if a new version introduces a new state file format, does the new version consume the old state file format files? -- If upgrades cannot be handled, document this. - -## Mandatory checks - -- Provide constructive comments on the code. - - If you particularly like some aspect of the code, say so. - - If you do not like something about the code, respectfully state what you do not like. - - If you do not understand the code, say so because code should **always** be clear. - -- Ensure all automated checks pass. -- Ensure the PR contains at least one `Fixes #issue-id` commit message referencing an issue that this PR fixes. diff --git a/README.md b/README.md index 2226b28..fdd814e 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,24 @@ -# KusionStack community +# Community -Welcome to the KusionStack community! +Welcome to the KusionStack open source community! Your participation is vital for the healthy growth of our open source projects. There are several ways you can get involved. You can create issues or fix bugs, improve documentation, or contribute code by submitting pull requests (PRs). The KusionStack project is always looking for new contributors and feedback. To get in touch, please refer to the links below. -This is the starting point for becoming a contributor - improving code and docs, giving talks, etc. +* [Open a New Discussion on GitHub](https://github.com/orgs/KusionStack/discussions) +* [Contact Us on Slack](https://app.slack.com/client/T03H6QE4VL0/setup-welcome) -## KusionStack Open Day +# CONTRIBUTING -- [2022/open-day/README.md](2022/open-day/README.md) +We appreciate contributions from the community! To submit changes, please refer to the contributing file in the corresponding KusionStack repository. The files are available at the following links: +* [Kusion](https://github.com/KusionStack/kusion/blob/main/docs/contributing.md) +* [Operating](https://github.com/KusionStack/operating/blob/main/docs/contributing.md) -## Other documents +# CODE OF CONDUCT +To make KusionStack a welcoming and harassment-free experience for everyone, we follow the [KusionStack Code of Conduct](CODE_OF_CONDUCT.md). -- [Community Roles](ROLES.md) - describes the roles individuals can assume within the KusionStack community. -- [Working Groups](WORKING-GROUPS.md) - to enhance community transparency and collaboration among community members, KusionStack created a series of working groups. -## Introduction +# Contact Us +- Twitter: [KusionStack](https://twitter.com/KusionStack) +- Slack: [Kusionstack](https://join.slack.com/t/kusionstack/shared_invite/zt-19lqcc3a9-_kTNwagaT5qwBE~my5Lnxg) +- DingTalk (Chinese): 42753001 +- Wechat Group (Chinese) -KusionStack is a Unified Programmable Configuration Tech Stack. - - -Visit [kusionstack.io](https://kusionstack.io) for more information about using KusionStack. - -## KusionStack authors - -KusionStack is an open source project started by [Ant Group](https://www.antgroup.com/) with an active development community. - -## Community meeting - -- Thursday 8:00 PM CST(Beijing 北京时间周四晚 8:00) ([钉钉(DingTalk ID 42753001)](https://h5.dingtalk.com/circle/healthCheckin.html?cbdbhh=qwertyuiop&dtaction=os&4ebe6=d3d59&corpId=ding707e3346ab188ded2040d0a6270bd858)) every other week -- Meeting notes: https://github.com/KusionStack/community/discussions/categories/meeting - -## Tutorials - -Learn KusionStack with book. - -- [KusionStack/kusion-in-action-book](https://github.com/KusionStack/kusion-in-action-book) - -## Contributing - -See [the contributing document](CONTRIBUTING.md). - -## Contact - -- [Slack/KusionStack](https://join.slack.com/t/kusionstack/shared_invite/zt-19lqcc3a9-_kTNwagaT5qwBE~my5Lnxg) -- [钉钉(DingTalk ID 42753001)](https://h5.dingtalk.com/circle/healthCheckin.html?cbdbhh=qwertyuiop&dtaction=os&4ebe6=d3d59&corpId=ding707e3346ab188ded2040d0a6270bd858) - -![](dingding-talk.jpg) + \ No newline at end of file diff --git a/ROLES.md b/ROLES.md index 74f4727..9e46bcb 100644 --- a/ROLES.md +++ b/ROLES.md @@ -4,11 +4,11 @@ This document describes the set of roles individuals may have within the KusionS ## User -A ***user*** is someone that uses KusionStack. They contribute to KusionStack projects by providing feedback to developers in the form of bug reports and feature suggestions. Users participate in the KusionStack community by helping other users. +A ***user*** is someone who uses KusionStack. They contribute to KusionStack projects by providing feedback to developers in the form of bug reports and feature suggestions. Users participate in the KusionStack community by helping other users. ## Contributor -A ***contributor*** is a user who contributes to the project in the form of code or documentation. They take extra steps to participate in a project, are active on the community, participate in discussions, provide patches, documentation, suggestions, and criticism. +A ***contributor*** is a user who contributes to the project in the form of code or documentation. They take extra steps to participate in a project, are active in the community, participate in discussions, and provide patches, documentation, suggestions, and criticism. ## Maintainer diff --git a/WORKING-GROUPS.md b/WORKING-GROUPS.md deleted file mode 100644 index 701ee09..0000000 --- a/WORKING-GROUPS.md +++ /dev/null @@ -1,22 +0,0 @@ -# KusionStack Working Groups - -To enhance community transparency and collaboration among community members, we created a series of working groups for KusionStack. - -## WG lists - -- [Kusion WG](wg-kusion.md) -- [KCL WG](wg-kcl.md) - -## WG leads - -The currently created working groups are: - -| Group | Lead | Description | -| ------ | ------ | ----------- | -| Kusion | [@elliotxx](https://github.com/elliotxx) | [Roadmap](https://kusionstack.io/docs/governance/intro/roadmap) | -| KCL | [@Peefy](https://github.com/Peefy) | [Roadmap](https://kusionstack.io/docs/governance/intro/roadmap) | - -## Community meeting - -- Regular meetings: Saturday 8:00 PM CST(Beijing) ([钉钉(DingTalk)](https://h5.dingtalk.com/circle/healthCheckin.html?cbdbhh=qwertyuiop&dtaction=os&4ebe6=d3d59&corpId=ding707e3346ab188ded2040d0a6270bd858)) every other week -- Meeting notes (Github Wiki): https://github.com/KusionStack/community/wiki diff --git a/dingding-talk.jpg b/dingding-talk.jpg deleted file mode 100644 index 38f5491..0000000 Binary files a/dingding-talk.jpg and /dev/null differ diff --git a/wg-kcl.md b/wg-kcl.md deleted file mode 100644 index de48b36..0000000 --- a/wg-kcl.md +++ /dev/null @@ -1,7 +0,0 @@ -# KCLVM Working Group - -Lead: [@Peefy](https://github.com/Peefy) - -## Roadmap - -KusionStack Kusion WG roadmap, see https://kusionstack.io/docs/governance/intro/roadmap. diff --git a/wg-kusion.md b/wg-kusion.md deleted file mode 100644 index 1870641..0000000 --- a/wg-kusion.md +++ /dev/null @@ -1,7 +0,0 @@ -# Kusion Working Group - -Lead: [@elliotxx](https://github.com/elliotxx) - -## Roadmap - -KusionStack Kusion WG roadmap, see https://kusionstack.io/docs/governance/intro/roadmap.