From 223b2e1f093d5012d289700623f17d913bcffc1b Mon Sep 17 00:00:00 2001 From: zhijian Date: Wed, 27 Jul 2022 13:19:02 +0800 Subject: [PATCH] doc: improve contributing guide doc (#2406) * improve contributing guide doc --- CONTRIBUTING.md | 16 ++++---- docs/en/development/contributing_guide.md | 43 ++++++++++++++++++-- docs/zh_cn/development/contributing_guide.md | 43 ++++++++++++++++++-- 3 files changed, 88 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c958590f392b..775b73c0c1a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,11 +9,11 @@ ## Coding Style -- We're following ["Effective Go"](https://golang.org/doc/effective_go.html) and ["Go Code Review Comments"](https://github.com/golang/go/wiki/CodeReviewComments). +- We're following ["Effective Go"](https://go.dev/doc/effective_go) and ["Go Code Review Comments"](https://github.com/golang/go/wiki/CodeReviewComments). - Use `go fmt` to format your code before committing. You can find information in editor support for Go tools in ["IDEs and Plugins for Go"](https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins). - If you see any code which clearly violates the style guide, please fix it and send a pull request. - Every new source file must begin with a license header. -- Install [pre-commit](https://pre-commit.com/) and use it to set up a pre-commit hook for static analysis. Just run `pre-commit install` in the root of the repo. +- Install [pre-commit](https://pre-commit.com) and use it to set up a pre-commit hook for static analysis. Just run `pre-commit install` in the root of the repo. ## Sign the CLA @@ -30,11 +30,11 @@ Before you can contribute to JuiceFS, you will need to sign the [Contributor Lic 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 `main`. -- Make commits of logical units. -- Make sure commit messages are in the proper format. -- Push changes in a topic branch to a personal fork of the repository. -- Submit a pull request to [juicedata/juicefs](https://github.com/juicedata/juicefs/compare). The PR should link to one issue which either created by you or others. -- The PR must receive approval from at least one maintainer before it be merged. +1. Create a topic branch from where to base the contribution. This is usually `main`. +1. Make commits of logical units. +1. Make sure commit messages are in the proper format. +1. Push changes in a topic branch to a personal fork of the repository. +1. Submit a pull request to [juicedata/juicefs](https://github.com/juicedata/juicefs/compare). The PR should link to one issue which either created by you or others. +1. The PR must receive approval from at least one maintainer before it be merged. Happy hacking! diff --git a/docs/en/development/contributing_guide.md b/docs/en/development/contributing_guide.md index 929dadaead20..1d8bbfa10f32 100644 --- a/docs/en/development/contributing_guide.md +++ b/docs/en/development/contributing_guide.md @@ -2,7 +2,44 @@ sidebar_label: Contributing Guide sidebar_position: 1 --- -# Contributing Guide -:::note -Working in progress. \ No newline at end of file +# Contributing to JuiceFS + +## Guidelines + +- Before starting work on a feature or bug fix, please search GitHub or reach out to us via GitHub, Slack etc. The purpose of this step is make sure no one else is already working on it and we'll ask you to open a GitHub issue if necessary. +- We will use the GitHub issue to discuss the feature and come to agreement. This is to prevent your time being wasted, as well as ours. +- If it is a major feature update, we highly recommend you also write a design document to help the community understand your motivation and solution. +- A good way to find a project properly sized for a first time contributor is to search for open issues with the label ["kind/good-first-issue"](https://github.com/juicedata/juicefs/labels/kind%2Fgood-first-issue) or ["kind/help-wanted"](https://github.com/juicedata/juicefs/labels/kind%2Fhelp-wanted). + +## Coding Style + +- We're following ["Effective Go"](https://go.dev/doc/effective_go) and ["Go Code Review Comments"](https://github.com/golang/go/wiki/CodeReviewComments). +- Use `go fmt` to format your code before committing. You can find information in editor support for Go tools in ["IDEs and Plugins for Go"](https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins). +- If you see any code which clearly violates the style guide, please fix it and send a pull request. +- Every new source file must begin with a license header. +- Install [pre-commit](https://pre-commit.com) and use it to set up a pre-commit hook for static analysis. Just run `pre-commit install` in the root of the repo. + +## Sign the CLA + +Before you can contribute to JuiceFS, you will need to sign the [Contributor License Agreement](https://cla-assistant.io/juicedata/juicefs). There're a CLA assistant to guide you when you first time submit a pull request. + +## What is a Good PR + +- Presence of unit tests +- Adherence to the coding style +- Adequate in-line comments +- Explanatory commit message + +## Contribution Flow + +This is a rough outline of what a contributor's workflow looks like: + +1. Create a topic branch from where to base the contribution. This is usually `main`. +1. Make commits of logical units. +1. Make sure commit messages are in the proper format. +1. Push changes in a topic branch to a personal fork of the repository. +1. Submit a pull request to [juicedata/juicefs](https://github.com/juicedata/juicefs/compare). The PR should link to one issue which either created by you or others. +1. The PR must receive approval from at least one maintainer before it be merged. + +Happy hacking! diff --git a/docs/zh_cn/development/contributing_guide.md b/docs/zh_cn/development/contributing_guide.md index f14ea707bc36..a106b3fba8b2 100644 --- a/docs/zh_cn/development/contributing_guide.md +++ b/docs/zh_cn/development/contributing_guide.md @@ -2,7 +2,44 @@ sidebar_label: 贡献指南 sidebar_position: 1 --- -# 贡献指南 -:::note 注意 -文档正在编写 \ No newline at end of file +# JuiceFS 贡献指南 + +## 基本准则 + +- 在开始修复功能或错误之前，请先通过 GitHub、Slack 等渠道与我们沟通。此步骤的目的是确保没有其他人已经在处理它，如有必要，我们将要求您创建一个 GitHub issue。 +- 我们使用 GitHub issue 来讨论功能并达成一致。这是为了防止彼此的时间被浪费。 +- 如果这是一个重大的特性更新，我们强烈建议你写一份设计文档来帮助社区理解你的动机和解决方案。 +- 对于首次贡献者来说找到合适 issue 的好方法是使用标签 ["kind/good-first-issue"](https://github.com/juicedata/juicefs/labels/kind%2Fgood-first-issue) 或 ["kind/help-wanted"](https://github.com/juicedata/juicefs/labels/kind%2Fhelp-wanted) 搜索未解决的问题。 + +## 代码风格 + +- 我们遵循 ["Effective Go"](https://go.dev/doc/effective_go) 和 ["Go Code Review Comments"](https://github.com/golang/go/wiki/CodeReviewComments)。 +- 在提交前使用 `go fmt` 格式化你的代码。你可以在 [Go 的编辑器和 IDE](https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins) 中找到支持 Go 的相关工具的信息。 +- 如果你看到任何明显违反风格指南的代码，请修复它并提交一个 PR 。 +- 每个新的源文件都必须以许可证头开始。 +- 安装 [pre-commit](https://pre-commit.com) 并使用它来设置一个预提交钩子来进行静态分析。只需在仓库根目录下运行 `pre-commit install` 即可。 + +## 签署 CLA + +在您为 JuiceFS 进行贡献之前，您需要签署[贡献者许可协议](https://cla-assistant.io/juicedata/juicefs)。当你第一次提交 PR 的时候，将有一个 CLA 助手指导你。 + +## 什么是好的 PR + +- 足够的单元测试 +- 遵循编码风格 +- 足够的行内注释 +- 简要解释的提交内容 + +## 贡献流程 + +这是一个贡献者工作流程的大致轮廓： + +1. 基于主分支创建一个要贡献的主题分支。这个主分支通常是 `main` 分支； +1. 提交代码； +1. 确保提交消息的格式正确； +1. 将主题分支中的更改推到个人 fork 的仓库； +1. 提交一个 PR 到 [juicedata/juicefs](https://github.com/juicedata/juicefs/compare) 仓库。 这个 PR 应该链接到你或其他人创建的一个 issue； +1. PR 在合并之前必须得到至少一个维护者的批准。 + +尽情享受极客的快乐吧！