docs: update documents for CONTRIBUTING

And fix keymap typo
adoyle-h · Jan 24, 2023 · 2510a2a · 2510a2a
1 parent 3ca9542
commit 2510a2a
Show file tree

Hide file tree

Showing 9 changed files with 283 additions and 38 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,52 @@
-## How to contribute
+# Contributing
 
-- All code and text must be written in English.
-- All commits must follow the [DCO](https://developercertificate.org/).
-- Commit message must follow the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/).
-- [How to test](./doc/test.md)
+## Any comments and suggestions are always welcome
+
+**Before opening new Issue/Discussion/PR, you should search related [Issues][issue]/[Discussions][discussion]/[PRs][PR] first** for avoiding to create duplicated links.
+
+- For new feature request, open a [discussion][], describe your demand concisely and clearly.
+- For new feature submit, open a [PR][], describe your demand and design concisely and clearly.
+- For bug report, open an [issue][], describe the bug concisely and clearly.
+- For bug fix, open a [PR][], concisely and clearly describe what you fixed.
+- For question and suggestion, open a [discussion][].
+- For anything not mentioned above, open a [discussion][].
+
+### No +1
+
+Do not post duplicated and useless comments like `+1`, `LOL`, `Me too`, `I too would like to see this issue fixed.`, `When is this issue going to be fixed?`.
+
+Such comments do not help fix issues. Please don't be offended if project admins delete such comments.
+
+Please [react to comments with emoji][github-reaction] instead of.
+
+### Use English AMAP
+
+For non-native English speakers, please communicate in English as much as possible.
+It is recommended to use [DeepL Translator](https://www.deepl.com/translator).
+
+## Before making a Pull Request
+
+Read below links before making any contributions.
+
+- [Developer Certificate of Origin](./doc/dev/dco.md)
+- [Code Styles](./doc/dev/code-styles.md)
+- [Git Message Style](./doc/dev/git-message.md)
+- [Test](./doc/dev/test.md)
+
+## Make a Pull Request
+
+All PRs should follow below conditions.
+
+- [ ] Git message is [valid](./doc/dev/git-message.md).
+- [ ] Code style lint pass.
+- [ ] Test cases all passed without errors.
+- [ ] Squash one Git commit per PR.
+- [ ] All git commits follow the [DCO](./doc/dev/dco.md).
+
+
+<!-- Links -->
+
+[issue]: https://github.com/adoyle-h/one.nvim/issues
+[discussion]: https://github.com/adoyle-h/one.nvim/discussions
+[PR]: https://github.com/adoyle-h/one.nvim/pulls
+[github-reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md
@@ -0,0 +1,58 @@
+# Contributing
+
+## 提建议，修 Bug，做贡献
+
+欢迎提供任何建议或者意见。
+
+**在创建新的 Issue/Discussion/PR 之前，你必须先搜索相关 [Issue][]/[Discussion][]/[PR][]**，避免创建重复的链接。
+
+- 请求新功能。请开一个 [discussion][]，简短且清晰地描述你的需求。
+- 提交新功能。请开一个 [PR][]，简短且清晰地描述你的需求和设计。
+- 报告 BUG。请开一个 [issue][]，简短且清晰地描述你发现的问题。
+- 修复 BUG。请开一个 [PR][]，简短且清晰地描述你修了什么。
+- 提问和建议。请开一个 [discussion][]。
+- 其他上面未提到的内容，请开一个 [discussion][] 来讨论。
+
+### 禁止 +1
+
+不要发重复或无用的内容，比如 `+1`，`哈哈`，`附议`，`我希望这问题能够得到修复`，`这问题啥时候修好？`。
+
+这样的评论无助于问题的解决。如果项目管理员删除了此类评论，请别生气。
+
+请[贴 emoji 标签反馈到评论上](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/)。
+
+### 尽量用英文
+
+对于非英语母语的人，请尽可能使用英语交流。
+推荐使用 [DeepL Translator](https://www.deepl.com/translator)。
+
+你也可以使用中文反馈意见。不过希望你尽可能使用英文。
+因为我们处于国际社区，英文更通用，方便外国人阅读理解你的意见。
+注意不要中英文混杂（专业词汇除外），请写完整的英文或中文语句。
+
+## 创建 Pull Request 之前
+
+在做贡献之前，请阅读以下链接。
+
+- [Developer Certificate of Origin](./doc/dev/dco.md)
+- [Code Styles](./doc/dev/code-styles.md)
+- [Git Message Style](./doc/dev/git-message.md)
+- [Test](./doc/dev/test.md)
+
+## 创建 Pull Request
+
+所有 PR 必须遵守以下条件。
+
+- [ ] Git message 必须[有效](./doc/dev/git-message.md)。
+- [ ] 代码风格检查通过。
+- [ ] 测试案例全部通过，无 error。
+- [ ] 每个 PR 只有一个 Git commit。
+- [ ] 所有 git commit 都已签署 [DCO](./doc/dev/dco.md)。
+
+
+<!-- Links -->
+
+[issue]: https://github.com/adoyle-h/one.nvim/issues
+[discussion]: https://github.com/adoyle-h/one.nvim/discussions
+[PR]: https://github.com/adoyle-h/one.nvim/pulls
+[github-reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
diff --git a/README.md b/README.md
@@ -17,6 +17,8 @@ All-in-one neovim configuration framework implemented with Lua. It is highly fle
   <summary>Click to expend/collapse plugin list</summary>
 
   - Plugin Manager: [vim-plug](lua/one/plugin-manager/vim-plug.lua) (default) or [packer](lua/one/plugin-manager/packer.lua)
+  - Vim Options: [vim-options](lua/one/plugins/vim-options.lua)
+  - Utilities: [plenary](https://github.com/nvim-lua/plenary.nvim) and [Penlight](https://github.com/lunarmodules/Penlight) and [nui](https://github.com/MunifTanjim/nui.nvim)
   - Dashboard: [alpha.nvim](lua/one/plugins/alpha.lua)
   - Outline: [aerial](lua/one/plugins/aerial.lua) (default) or [majutsushi/tagbar](lua/one/plugins/tagbar.lua)
   - File Explorer: [neo-tree](lua/one/plugins/neo-tree.lua) (default) or [nerdtree](lua/one/plugins/nerdtree.lua) or [nvim-tree](lua/one/plugins/nvim-tree.lua)
@@ -74,6 +76,7 @@ All-in-one neovim configuration framework implemented with Lua. It is highly fle
   - Color Highlighter: [ccc.nvim](lua/one/plugins/colors/ccc.lua) (default) or [vim-hexokinase](lua/one/plugins/colors/hexokinase.lua) or [nvim-colorizer](lua/one/plugins/colors/colorizer.lua)
   - Translation: [translate.nvim](lua/one/plugins/translate.lua)
   - [Games](lua/one/plugins/funny.lua)
+  - one.nvim enhanced plugin: [one](lua/one/plugins/one.lua)
 
   </details>
 
@@ -255,20 +258,7 @@ Enable [profiling](./lua/one/plugins/profiling.lua) plugin, and invoke `:Startup
 
 ## Suggestion, Bug Reporting, Contributing
 
-Any comments and suggestions are always welcome.
-
-**Before open an issue/discussion/PR, You should search related [issue][]/[discussion][]/[PR][] first** for avoiding to create duplicated links.
-
-- For new feature request, open a [discussion][], describe your demand concisely and clearly.
-- For new feature submit, open a [PR][], describe your demand and design concisely and clearly.
-- For bug report, open an [issue][], describe the bug concisely and clearly.
-- For bug fix, open a [PR][], concisely and clearly describe what you fixed.
-- For question and suggestion, open a [discussion][].
-- For anything not mentioned above, open a [discussion][].
-
-Do not post duplicated and useless contents like `+1`, `LOL`. React to comments with emoji instead of.
-
-And read [how to contribute](CONTRIBUTING.md).
+Please read [./CONTRIBUTING.md](./CONTRIBUTING.md) before opening new Issue/Discussion/PR and posting any comments.
 
 ## Copyright and License
 

diff --git a/README.zh.md b/README.zh.md
@@ -17,6 +17,8 @@ Click [./README.md](./README.md) to read English documents.
   <summary>点击展开/折叠插件列表</summary>
 
   - 插件管理器: [vim-plug](lua/one/plugin-manager/vim-plug.lua) (默认) 或 [packer](lua/one/plugin-manager/packer.lua)
+  - Vim 选项: [vim-options](lua/one/plugins/vim-options.lua)
+  - 工具函数: [plenary](https://github.com/nvim-lua/plenary.nvim) 和 [Penlight](https://github.com/lunarmodules/Penlight) 和 [nui](https://github.com/MunifTanjim/nui.nvim)
   - 面板: [alpha.nvim](lua/one/plugins/alpha.lua)
   - 大纲: [aerial](lua/one/plugins/aerial.lua) (默认) 或 [majutsushi/tagbar](lua/one/plugins/tagbar.lua)
   - 文件浏览器: [neo-tree](lua/one/plugins/neo-tree.lua) (默认) 或 [nerdtree](lua/one/plugins/nerdtree.lua) 或 [nvim-tree](lua/one/plugins/nvim-tree.lua)
@@ -74,6 +76,7 @@ Click [./README.md](./README.md) to read English documents.
   - 颜色着色: [ccc.nvim](lua/one/plugins/colors/ccc.lua) (默认) 或 [vim-hexokinase](lua/one/plugins/colors/hexokinase.lua) 或 [nvim-colorizer](lua/one/plugins/colors/colorizer.lua)
   - 翻译: [translate.nvim](lua/one/plugins/translate.lua)
   - [游戏](lua/one/plugins/funny.lua)
+  - One.nvim 增强插件: [one](lua/one/plugins/one.lua)
 
   </details>
 
@@ -255,23 +258,7 @@ require('one').setup {
 
 ## 提建议，修 Bug，做贡献
 
-欢迎提供任何建议或者意见。
-
-**在开 issue/discussion/PR 之前，你必须先搜索相关 [issue][]/[discussion][]/[PR][]**，避免创建重复的链接。
-
-- 请求新功能。请开一个 [discussion][]，简短且清晰地描述你的需求。
-- 提交新功能。请开一个 [PR][]，简短且清晰地描述你的需求和设计。
-- 报告 BUG。请开一个 [issue][]，简短且清晰地描述你发现的问题。
-- 修复 BUG。请开一个 [PR][]，简短且清晰地描述你修了什么。
-- 提问和建议。请开一个 [discussion][]。
-- 其他上面未提到的内容，请开一个 [discussion][] 来讨论。
-
-不要发重复或无用的内容，比如 `+1`，`哈哈`。请贴 emoji 标签反馈到评论上。
-
-你可以使用中文反馈意见。但希望你尽可能使用英文，不要中英文混杂，而是写下完整的英文语句。
-因为我们处于国际社区，英文更通用，方便外国人阅读理解你的意见。
-
-请阅读[如何为本项目贡献](./CONTRIBUTING.md)。
+在创建新的 Issue/Discussion/PR，以及发表评论之前，请先阅读 [./CONTRIBUTING.zh.md](./CONTRIBUTING.zh.md)。
 
 ## 版权声明
 

diff --git a/doc/dev/code-styles.md b/doc/dev/code-styles.md
@@ -0,0 +1,20 @@
+# Code Styles
+
+## First of all
+
+- Your IDE must support [editorconfig](http://editorconfig.org/) and recognize the [`.editorconfig`](./.editorconfig) file in project.
+- All code and text must be written in English.
+
+## File naming
+
+All file names must match the regex `[a-z0-9-_]`, except `Dockerfile` and other particular files.
+
+## Shell script code styles
+
+- `[[ ... ]]` is preferred over `[ ... ]`, `test` and `/usr/bin/[`.
+- Function declaration `func() {...}` is preferred over `function func() {...}`.
+- Read-only Variables. Use `readonly` or `declare -r` to ensure they're read only.
+- Local Variables. Declare function-specific variables with `local`. Declaration and assignment should be on different lines.
+- Use `$(command)` instead of backticks.
+- `eval` should be avoided in most scenarios.
+- Constants and environment variable names must be all caps, separated with underscores.
diff --git a/doc/dev/dco.md b/doc/dev/dco.md
@@ -0,0 +1,89 @@
+# Developer Certificate of Origin
+
+The project uses a mechanism known as a Developer Certificate of Origin (DCO) to manage process.
+
+A DCO is a lightweight way for a developer to certify that they wrote or otherwise have the right
+to submit code or documentation to a project. The way a developer does this is by adding
+a Signed-off-by line to a commit. When they do this they are agreeing to the DCO.
+
+The full text of the DCO can be found at https://developercertificate.org . It reads:
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```
+
+If you are willing to agree to these terms, you just add a line to every git commit message:
+
+```
+Signed-off-by: Some Developer somedev@example.com
+```
+
+If you set your user.name and user.email as part of your git configuration,
+you can sign your commit automatically with `git commit -sS`.
+
+An example signed commit message might look like:
+
+```
+An example commit message
+
+Signed-off-by: Some Developer somedev@example.com
+```
+
+If more than one person works on something it’s possible for more than one person to sign off on it. For example,
+
+```
+An example commit message
+
+Signed-off-by: Some Developer somedev@example.com
+Signed-off-by: Another Developer anotherdev@example.com
+```
+
+
+See `git help commit`,
+
+```
+-s, --signoff
+    Add Signed-off-by line by the committer at the end of the commit log message. The meaning of a signoff depends on the
+    project, but it typically certifies that committer has the rights to submit this work under the same license and
+    agrees to a Developer Certificate of Origin (see http://developercertificate.org/ for more information).
+
+-S[<keyid>], --gpg-sign[=<keyid>]
+    GPG-sign commits. The keyid argument is optional and defaults to the committer identity; if specified, it must be
+    stuck to the option without a space.
+```
diff --git a/doc/dev/git-message.md b/doc/dev/git-message.md
@@ -0,0 +1,55 @@
+# Git Commit Message Style
+
+Generally follows the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/).
+
+## Commit Message Format
+
+```
+<type>[(scope)][!]: <description>
+
+[optional body]
+
+[optional footer]
+```
+
+`[(scope)]` is optional.
+
+## Type
+
+Must be one of the following:
+
+- **build**: Changes that affect the build system or external dependencies
+- **ci**: Changes to our CI configuration files and scripts
+- **docs**: Documentation only changes
+- **feat**: A new feature
+- **fix**: A bug fix
+- **perf**: A code change that improves performance
+- **refactor**: A code change that neither fixes a bug nor adds a feature
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- **test**: Adding missing tests or correcting existing tests
+- **chore**: Other changes that don't modify src or test files
+
+
+## Breaking Change
+
+Commit message with optional `!` to draw attention to breaking change.
+
+```
+chore!: drop Node 6 from testing matrix
+
+BREAKING CHANGE: dropping Node 6 which hits end of life in April
+```
+
+A commit that has the text `BREAKING CHANGE:` at the beginning of its optional body or footer section
+introduces a breaking API change (correlating with MAJOR in semantic versioning).
+A BREAKING CHANGE can be part of commits of any type.
+
+## Sign the DCO for PR
+
+Please sign our Developer Certificate of Origin (DCO) before sending pull requests. For any code changes to be accepted, the DCO must be signed. It's very simple. See [this document](./dco.md).
+
+## Squash git commits for PR
+
+Each Pull Request should do one thing in only one commit.
+
+You can use `git rebase -i` to squash some commits into one.
diff --git a/doc/test.md → doc/dev/test.md b/doc/test.md → doc/dev/test.md
diff --git a/doc/usage/keymaps.md b/doc/usage/keymaps.md
@@ -278,8 +278,8 @@ If bufferline plugin enabled, some keymaps will be overridden. See [Buffer Line]
 - `<M-W>` = Focus to previous window
 - `<C-w>p` = Focus to last accessed window.
 - `<C-w>q` = Close current window
-- `<C-w>|` = Open split window
-- `<C-w>\` or `<C-w>n` = Open vsplit window
+- `<C-w>|` = Open window (vsplit)
+- `<C-w>\` or `<C-w>n` = Open window (split)
 - `<C-w>r` = Enter window resize mode
 - `<C-w>h` = Focus to left window
 - `<C-w>j` = Focus to bottom window