SpaceVim

一个模块化的 Vim/Neovim 配置集合

开发者文档

寻求帮助
反馈问题
贡献代码
基于 SpaceVim 开发
更新日志

SpaceVim 是每个志愿者的努力的结晶，我们鼓励你参与进来，SpaceVim 是由社区驱动的。下面是关于每个贡献者都应当遵守的简单规则的引导。

你可以只阅读下面内容中的，你需要用到的部分：

Asking for help 建立 issue 的帮助
Reporting issues 反馈问题的帮助
Contributing code 建立 PR 的帮助

寻求帮助

当遇到问题时，建议先查阅FAQ以及使用文档

反馈问题

请先阅读下面内容，再通过邮件进行反馈：

检查错误追踪中是否存在重复的问题，你可以通过在错误追踪中搜索关键词来确认错误追踪中是否存在重复的问题
检查问题是否在最新版的 SpaceVim 中修复，请更新你的 SpaceVim，然后进行 Bug 重现操作
按照下面的问题格式，建立清晰的问题标题
包括 Bug 出现的细节，一步一步重现 Bug 出现的操作

贡献代码

我们非常期待您的贡献。在此之前，请您认真阅读下面的内容。

代码结构

├─ .SpaceVim.d/                   开发者配置
├─ autoload/SpaceVim.vim          核心逻辑文件
├─ autoload/SpaceVim/api/         公共函数（API）
├─ autoload/SpaceVim/layers/      可用模块
├─ autoload/SpaceVim/plugins/     内置插件
├─ autoload/SpaceVim/mapping/     快捷键
├─ doc/                           帮助文档
├─ docs/                          网站源码
├─ bin/                           可执行命令
└─ test/                          测试文件

许可

SpaceVim 所有部分采用 GPLv3 许可。

初始化及核心代码
所有模块相关文件

额外的依赖文件，请参阅文件头许可信息，这些文件不应该使用空白文件头，我们也不会接受空白文件头的代码。

公约

提交代码时，需要遵循一些约定，主要包括函数的命名格式、文档的写法、快捷键定义的规范等，具体内容可以查阅《格式规范》, 在您进行贡献前，请确认您已经了解了以上公约的内容。

合并请求

操作步骤

以下步骤介绍了如何使用邮件新建合并请求

在github、gitlab或者其他任意代码平台新建空白仓库
克隆你自己的空白仓库
```
git clone ${YOUR_OWN_REPOSITORY_URL}
```

添加上游远程仓库地址

git remote add upstream https://spacevim.org/git/repos/SpaceVim/

基于upstream/master新建分支

git fetch upstream
git checkout -b new_branch upstream/master

修改并commit后，推送至自己的仓库
```
git push -u origin
```
发送拉取请求邮件至邮件组
- 邮箱地址：[email protected]
- 邮件标题:
  
  新开拉取请求时，应当通过标题前缀来标记该拉取请求的性质：
  - Add: 添加新的特性
  - Change: 修改已有特性的行为
  - Fix: 修复某些问题
  - Remove: 移除原先支持的某些特性
  - Doc: 更新帮助文档
  - Website: 更新网站内容
  - Type: 更新错别字
  示例如下：
  
  Fix: 修复 scrollbar 高亮
- 邮件内容：
  
  邮件内容主要要包括你的仓库地址及分支名称，最好增加一些分支变更的具体描述内容，比如：
```
repo url: https://gitlab.com/wsdjeg/hello.git
branch: fix_scrollbar

scrollbar 在窗口切换时，高亮颜色错误。具体重现步骤如下：

。。。。
```

简单合并请求

master中的分支
每个 PR 一个主题
每个 PR 一个提交
如果你有一些不同主题的提交，请关闭 PR 然后为每个主题创建一个新的 PR
如果你仍然有很多提交，请把它们打包成一个提交

复杂合并请求

只打包一些枯燥的提交，比如修改错别字，语法修复，等等。把重要和独立的步骤分别放在不同的提交中。这些 PRs 被合并并且明示非快速转发。提交信息根据编写的内容提交信息 Tim Pope’s guidelines：

用现在时和祈使句：例如：”Fix bug”，而不是”fixed bug” 或者”fixes bug”。
以大写字母开头，短摘要开头（72 个字符或者更少），以空行结尾。
如果需要的话，可以用每行 72 个字符的格式添加一个或多个详细的段落。
每个独立的段落以空行结尾。

这是一个提交信息的模版：

Capitalized, short (72 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

    - Typically a hyphen or asterisk is used for the bullet, followed by a
      single space, with blank lines in between, but conventions vary here

    - Use a hanging indent

贡献一个模块

首先需要阅读模块文档，了解什么是模块，以及模块应包括那些内容。

未关联配置的模块将会被拒绝。举个例子一个只有包和钩子的模块，就能被很简单地替换为变量 g:spacevim_custom_plugins。

文件头

Vim 脚本的文件头，应该采用下面的格式：

"=============================================================================
" FILENAME --- NAME layer file for SpaceVim
" Copyright (c) 2012-2022 Shidong Wang & Contributors
" Author: YOUR NAME <YOUR EMAIL>
" URL: https://spacevim.org
" License: GPLv3
"=============================================================================

你应该用文件（比如：foo.vim）来替换掉 FILENAME，把 NAME 用你编写的 layer 的名字来代替，同时不要忘了替换 YOUR NAME 和 YOUR EMAIL。

新 layer 的作者

把文件头中的默认作者名字（Shidong Wang）改为你自己的名字。

下面是一个创建一个名字为 foo 的新 layer 的示例

fork SpaceVim repo
add a layer file autoload/SpaceVim/layers/foo.vim for foo layer.
edit layer file, check out the example below:

"=============================================================================
" foo.vim --- foo Layer file for SpaceVim
" Copyright (c) 2012-2022 Shidong Wang & Contributors
" Author: Shidong Wang < [email protected] >
" URL: https://spacevim.org
" License: GPLv3
"=============================================================================

""
" @section foo, layers-foo
" @parentsection layers
" This the doc for this layer:
"
" @subsection Key Bindings
" >
"   Modes     Keys            Functions
"   -------------------------------------------------------------
"   normal    <leader> j A    generate accessors
"   normal    <leader> j s    generate setter accessor
" <
" @subsection Layer options
" >
"   Names             Descriptions                     Default
"   -------------------------------------------------------------
"   option1           Set option1 for foo layer        ''
"   option2           Set option2 for foo layer        []
"   option3           Set option3 for foo layer        {}
" <
" @subsection Global options
" >
"   Names             Descriptions                     Default
"   -------------------------------------------------------------
"   g:pluginA_opt1    Set opt1 for plugin A               ''
"   g:pluginB_opt2    Set opt2 for plugin B               []
" <

function! SpaceVim#layers#foo#plugins() abort
  let plugins = []
  call add(plugins, ['Shougo/foo.vim', {'option' : 'value'}])
  call add(plugins, ['Shougo/foo_test.vim', {'option' : 'value'}])
  return plugins
endfunction

function! SpaceVim#layers#foo#config() abort
  let g:foo_option1 = get(g:, 'foo_option1', 1)
  let g:foo_option2 = get(g:, 'foo_option2', 2)
  let g:foo_option3 = get(g:, 'foo_option3', 3)
  " ...
endfunction

Add layer document docs/layers/foo.md for foo layer.
Open docs/layers/index.md, run :call SpaceVim#dev#layers#update() to update layer list.
send PR to SpaceVim.

改进现有的模块

现有的模块头文件中包含了作者等信息，这些信息通常不可修改。对现有的模块进行改进时，需要尽量保持原先的默认行为。

贡献按键绑定

按键映射是 SpaceVim 中非常重要的一部分。

如果你只想要拥有自己的按键映射的话，你可以在启动函数文件中进行新增。

如果你认为贡献一个新的按键映射有必要，那么请首先阅读文档，把自己的按键映射调整为最佳状态，然后用你更改后的按键映射进行提交 PR。

始终牢记，在相关文档中记录新的按键映射或者是按键映射更改。它应该是 layername.md 和 documentation.md。

特定语言的按键绑定

所有语言的专属按键绑定都是以 SPC l 前缀开始的。

快捷键	功能描述
`SPC l r`	为当前文件打开一个 runner
`SPC l e`	rename symbol
`SPC l d`	显示文档
`SPC l i r`	删除未使用的导包
`SPC l i s`	排序导包
`SPC l s i`	开启一个语言专属的 REPL 进程
`SPC l s b`	后台发送当前缓冲区
`SPC l s l`	后台发送当前行
`SPC l s s`	后台发送选中文本

上面所有的按键绑定都是默认的建议，但是它同样是基于自身的语言层的。

欢迎界面LOGO

启动界面的LOGO默认是SpaceVim内置的一些ASCII码绘制的图形，存储于 core/banner 模块， LOGO需要选择合适的高度，宽度限定90个字符宽度以内，高度限定在10以内。

基于 SpaceVim 开发

SpaceVim 提供了一套内置的公共函数库（API），可以基于这个公共函数开发兼容 Vim 和 Neovim 的插件。同时，也可以向插件的 README 中添加 SpaceVim 的图标：

markdown 语法如下：

[![](https://spacevim.org/img/build-with-SpaceVim.svg)](https://spacevim.org/cn/)

更新日志

SpaceVim 发布 v2.3.0
24 Mar 2024
SpaceVim 发布 v2.3.0，使用 Lua 重写了大部分内置插件