SpaceVim

A community-driven vim distribution

Home | About | Quick start guide | Documentation | Development | Community | Sponsors

Home » Development

SpaceVim is an effort of all the volunteers. We encourage you to pitch in. The community makes SpaceVim what it is. We have a few guidelines which we need all contributors to follow.

You can only consider reading the sections relevant to what you are going to do:

Asking for help

If you want to ask an usage question, be sure to look first into some places as it may hold the answers:

Bug reporting

To report a bug, you can use the spacevim mailing list [email protected], before sending mail, please:

Contributing code

Code contributions are welcome. Please read the following sections carefully. In any case, feel free to join us on the gitter chat to ask questions about contributing!

License

The license is GPLv3 for all the parts of SpaceVim. This includes:

For files not belonging to SpaceVim like local packages and libraries, refer to the header file. Those files should not have an empty header, we may not accept code without a proper header file.

Conventions

SpaceVim is based on conventions, mainly for naming functions, keybindings definition and writing documentation. Please read the conventions before your first contribution to get to know them.

Git commit style guide

A git commit message consists a three distinct parts separated by black line.

Type (scope): Subject

body

footer

types

scopes

subject

Subjects should be no greater than 50 characters, should begin with a capital letter and do not end with a period.

Use an imperative tone to describe what a commit does, rather than what it did. For example, use change; not changed or changes.

body

Not all commits are complex enough to warrant a body, therefore it is optional and only used when a commit requires a bit of explanation and context.

The footer is optional and is used to reference issue tracker IDs.

Pull Request

Title prefix of pull request

Pull request titles should contain one of these prefixes:

Here is an example:

Website: Update the lang#c layer page.

Rebase on top of upstream master

Ideally for simple PRs

For complex PRs

Squash only the commits with uninteresting changes like typos, syntax fixes, etc. And keep the important and isolated steps in different commits.

Those PRs are merged and explicitly not fast-forwarded.

Contributing a layer

Please read the layers documentation first.

Layer with no associated configuration will be rejected. For instance a layer with just a package and a hook can be easily replaced by the usage of the variable custom_plugins.

File header

The file header for Vim script should look like the following template:

"=============================================================================
" FILENAME --- NAME layer file for SpaceVim
" Copyright (c) 2016-2020 Wang Shidong & Contributors
" Author: Wang Shidong < [email protected] >
" URL: https://spacevim.org
" License: GPLv3
"=============================================================================

You should replace FILENAME by the name of the file (e.g. foo.vim) and NAME by the name of the layer you are creating, don’t forget to replace YOUR NAME and YOUR EMAIL too.

Author of a new layer

In the file’s header, replace the default author name (Shidong Wang) with your name.

The following example shows how to create a new layer named foo:

  1. Fork SpaceVim repo.
  2. Add a layer file autoload/SpaceVim/layers/foo.vim for foo layer.
  3. Edit layer file, check out the example below:
"=============================================================================
" foo.vim --- foo Layer file for SpaceVim
" Copyright (c) 2012-2016 Shidong Wang & Contributors
" Author: Shidong Wang < wsdjeg at 163.com >
" URL: https://spacevim.org
" License: GPLv3
"=============================================================================

""
" @section foo, layer-foo
" @parentsection layers
" This is the doc for this layer:
"
" @subsection Key Bindings
" >
"   Mode      Key           Function
"   -------------------------------------------------------------
"   normal    <leader>jA    generate accessors
"   normal    <leader>js    generate setter accessor
" <
" @subsection Layer options
" >
"   Name              Description                      Default
"   -------------------------------------------------------------
"   option1       Set option1 for foo layer               ''
"   option2       Set option2 for foo layer               []
"   option3       Set option3 for foo layer               {}
" <
" @subsection Global options
" >
"   Name              Description                      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 options:
let s:layer_option = 'default var'
function! SpaceVim#layers#foo#set_variable(var) abort
  let s:layer_option = get(a:var, 'layer_option', s:layer_option)
endfunction

" completion function for layer options:
function! SpaceVim#layers#foo#get_options() abort
    return ['layer_option']
endfunction
  1. Create the layer’s documentation file docs/layers/foo.md for foo layer.
  2. Open docs/layers/index.md, and run :call SpaceVim#dev#layers#update() to update the layers list.
  3. Send a PR to SpaceVim.

Contributor to an existing layer

If you want to contribute to an already existing layer, you should not modify any header file.

Contributing a keybinding

Mappings are an important part of SpaceVim.

First if you want to have some personal mappings. This can be done in your bootstrap function.

If you think it is worth contributing new mappings, be sure to read the documentation to find the best mappings, then create a Pull-Request with your mappings.

ALWAYS document your new mappings or mapping changes inside the relevant documentation file. It should be the layername.md and the documentation.

Language specified key bindings

All language specified key bindings have the prefix SPC l.

We recommend you to use the common language specified key bindings for the same purpose as the following:

Key Binding Description
SPC l r start a runner for current file
SPC l e rename symbol
SPC l d show doc
SPC l i r remove unused imports
SPC l i s sort imports with isort
SPC l s i Start a language specified inferior REPL process
SPC l s b send buffer and keep code buffer focused
SPC l s l send line and keep code buffer focused
SPC l s s send selection text and keep code buffer focused

All above key bindings are just recommended as default, but they are also based on the language layer itself.

Contributing a banner

The startup banner is by default the SpaceVim logo but there are also ASCII banners available in the core/banner layer.

If you have some ASCII skills you can submit your artwork!

You are free to choose a reasonable height size but the width size should be around 75 characters.

Build with SpaceVim

SpaceVim provides a lot of public APIs, you can create plugins based on these APIs. Also you can add a badge to the README.md of your plugin.

markdown

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

Newsletters

Changelog

Powered by Jekyll, Help improve this page