mirror of
https://github.com/SpaceVim/SpaceVim.git
synced 2025-01-24 02:10:05 +08:00
425 lines
14 KiB
Markdown
425 lines
14 KiB
Markdown
---
|
||
title: "Development"
|
||
description: "General contributing guidelines and changelog of SpaceVim, including development information about SpaceVim"
|
||
---
|
||
|
||
# Development
|
||
|
||
<!-- vim-markdown-toc GFM -->
|
||
|
||
- [Asking for help](#asking-for-help)
|
||
- [Reporting bugs](#reporting-bugs)
|
||
- [Requesting new feature](#requesting-new-feature)
|
||
- [Contributing code](#contributing-code)
|
||
- [License](#license)
|
||
- [Conventions](#conventions)
|
||
- [Commit style guide](#commit-style-guide)
|
||
- [Pull Request](#pull-request)
|
||
- [Prefix of title](#prefix-of-title)
|
||
- [Workflow](#workflow)
|
||
- [Simple PRs](#simple-prs)
|
||
- [Complex PRs](#complex-prs)
|
||
- [Contributing a layer](#contributing-a-layer)
|
||
- [File header](#file-header)
|
||
- [Author of a new layer](#author-of-a-new-layer)
|
||
- [Contributor to an existing layer](#contributor-to-an-existing-layer)
|
||
- [Contributing a keybinding](#contributing-a-keybinding)
|
||
- [Language specified key bindings](#language-specified-key-bindings)
|
||
- [Contributing a banner](#contributing-a-banner)
|
||
- [Build with SpaceVim](#build-with-spacevim)
|
||
- [Newsletters](#newsletters)
|
||
- [Changelog](#changelog)
|
||
|
||
<!-- vim-markdown-toc -->
|
||
|
||
SpaceVim is a joint effort of all contributors.
|
||
We encourage you to participate in SpaceVim's development.
|
||
This page describes the entire development process of SpaceVim.
|
||
|
||
We have some guidelines that we need all contributors to follow.
|
||
You can only think about reading the part that is relevant to what you are going to do:
|
||
|
||
- [Asking for help](#asking-for-help): if you are about to open an issue to ask a question.
|
||
- [Requesting new feature](#requesting-new-feature): if you want a new feature.
|
||
- [Reporting bugs](#reporting-bugs): if you run into a bug.
|
||
- [Contributing code](#contributing-code): if you are about to send a pull-request.
|
||
|
||
## Asking for help
|
||
|
||
If you have any questions about using SpaceVim,
|
||
check out the following context first, which may contain the answers:
|
||
|
||
- `:h SpaceVim-faq`: Some of the most frequently asked questions are answered there.
|
||
- [SpaceVim documentation](https://spacevim.org/documentation/): It is the general documentation of SpaceVim.
|
||
|
||
Besides, you can also [chat with us](../community/#chat)
|
||
|
||
## Reporting bugs
|
||
|
||
If you run into a bug, please follow the guidelines below to give feedback.
|
||
|
||
- Check that no duplicate issue in [issue tracker](https://github.com/SpaceVim/SpaceVim/issues)
|
||
- Check that the issue has not been fixed in latest version of SpaceVim,
|
||
please update your SpaceVim, and try to reproduce the bug here.
|
||
- Use a clear title with `bug reporting` issue template
|
||
|
||
```
|
||
<!-- bug reporting without issue template will be closed automatically -->
|
||
## Expected behavior, english is required
|
||
|
||
## The reproduce ways from Vim starting (Required!)
|
||
|
||
## Debug info
|
||
<!-- Please press SPC h I, debug info will be put into clipboard, -->
|
||
<!-- then paste all content below. -->
|
||
|
||
## Screenshots
|
||
<!-- If you have any screenshots for this issue, -->
|
||
<!-- please upload here. -->
|
||
<!-- BTW you can use https://asciinema.org/ for recording video in terminal. -->
|
||
```
|
||
|
||
## Requesting new feature
|
||
|
||
If you want a new feature, use the [github issue tracker](https://github.com/SpaceVim/SpaceVim/issues) to file a new issue.
|
||
You need to choose a concise title and refine the content in the issue template:
|
||
|
||
```
|
||
**Is your feature request related to a problem? Please describe.**
|
||
<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
|
||
|
||
**Describe the solution you'd like**
|
||
<!-- A clear and concise description of what you want to happen. -->
|
||
|
||
**Describe alternatives you've considered**
|
||
<!-- A clear and concise description of any alternative solutions or features you've considered. -->
|
||
|
||
**Additional context**
|
||
<!-- Add any other context or screenshots about the feature request here. -->
|
||
```
|
||
|
||
## Contributing code
|
||
|
||
Code and documentation contributions of any kind are welcome.
|
||
Please read the following sections carefully.
|
||
In any case, feel free to [chat with us](../community/#chat) to ask questions about contributing!
|
||
|
||
### License
|
||
|
||
The license is GPLv3 for all the parts of SpaceVim. This includes:
|
||
|
||
- The initialization and core files.
|
||
- All the layer files.
|
||
- The documentation
|
||
|
||
For files not belonging to SpaceVim like bundle packages,
|
||
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 these [conventions](../conventions/) to make sure you
|
||
understand them before you contribute code or documentation for the first time.
|
||
|
||
### Commit style guide
|
||
|
||
Follow the [conventional commits guidelines](https://www.conventionalcommits.org/) to _make reviews easier_ and to make the git logs more valuable.
|
||
The general structure of a commit message is:
|
||
|
||
```
|
||
<type>([optional scope]): <description>
|
||
|
||
[optional body]
|
||
|
||
[optional footer(s)]
|
||
```
|
||
|
||
**types:**
|
||
|
||
- `feat`: A new feature
|
||
- `fix`: A bug fix
|
||
- `docs`: Documentation only changes
|
||
- `style`: Changes that do not affect the meaning of the code
|
||
- `refactor`: A code change that neither fixes a bug nor adds a feature
|
||
- `pref`: A code change that improves performance
|
||
- `test`: Adding missing tests or correcting existing tests
|
||
- `ci`: Changes to our CI configuration files and scripts
|
||
- `chore`: Other changes that don't modify src or test files
|
||
- `revert`: Reverts a previous commit
|
||
|
||
**scopes:**
|
||
|
||
- `api`: files in `autoload/SpaceVim/api/` and `docs/api/` directory
|
||
- `layer`: files in `autoload/SpaceVim/layers/` and `docs/layers/` directory
|
||
- `plugin`: files in `autoload/SpaceVim/plugins/` directory
|
||
- `bundle`: files in `bundle/` directory
|
||
- `core`: other files in this repository
|
||
|
||
In addition to these scopes above,
|
||
you can also use a specific layer name or plugin name as a scope.
|
||
|
||
**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.
|
||
|
||
**footer**
|
||
|
||
The footer is optional and is used to reference issue tracker IDs.
|
||
|
||
|
||
**Breaking change**
|
||
|
||
Breaking changes must be indicated by "!" after the type/scope, and
|
||
a "BREAKING CHANGE" footer describing the change. Example:
|
||
|
||
```
|
||
refactor(tools#mpv)!: change default musics_directory
|
||
|
||
BREAKING CHANGE: `~/Music` is standard on macOS and
|
||
also on FreeDesktop's XDG.
|
||
```
|
||
|
||
### Pull Request
|
||
|
||
#### Prefix of title
|
||
|
||
The title of a pull request should contain one of the following prefixes::
|
||
|
||
- `Add:` Adding new features.
|
||
- `Change:` Change default behaviors or the existing features.
|
||
- `Fix:` Fix some bugs.
|
||
- `Remove:` Remove some existing features.
|
||
- `Doc:` Update the help files.
|
||
- `Website:` Update the content of website.
|
||
|
||
Here is an example:
|
||
|
||
`Website: Update the lang#c layer page.`
|
||
|
||
#### Workflow
|
||
|
||
- Fork SpaceVim repository
|
||
- Clone your repository
|
||
|
||
```sh
|
||
git clone ${YOUR_OWN_REPOSITORY_URL}
|
||
```
|
||
|
||
- Add upstream remote
|
||
|
||
```sh
|
||
git remote add upstream https://github.com/SpaceVim/SpaceVim.git
|
||
```
|
||
|
||
- Fetch upstream and rebase on top of upstream master
|
||
|
||
```sh
|
||
git fetch upstream
|
||
git rebase upstream/master
|
||
```
|
||
|
||
#### Simple PRs
|
||
|
||
- Branch from `master`
|
||
- One topic per PR
|
||
- One commit per PR
|
||
- If you have several commits on different topics, close the PR and create one PR per topic
|
||
- If you still have several commits, squash them into only one commit
|
||
|
||
#### 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:
|
||
|
||
```vim
|
||
"=============================================================================
|
||
" FILENAME --- NAME layer file for SpaceVim
|
||
" Copyright (c) 2016-2022 Wang Shidong & Contributors
|
||
" Author: Wang Shidong < wsdjeg@outlook.com >
|
||
" 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:
|
||
|
||
```vim
|
||
"=============================================================================
|
||
" 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, layers-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
|
||
```
|
||
|
||
4. Create the layer's documentation file `docs/layers/foo.md` for `foo` layer.
|
||
5. Open `docs/layers/index.md`, and run `:call SpaceVim#dev#layers#update()` to update the layers list.
|
||
6. 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](../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](../api/), you can create plugins based on these APIs. Also you can add a badge to the README.md of your plugin.
|
||
|
||
|
||
|
||
markdown
|
||
|
||
```md
|
||
[](https://spacevim.org)
|
||
```
|
||
|
||
## Newsletters
|
||
|
||
<ul>
|
||
{% for post in site.categories.newsletter %}
|
||
<li>
|
||
<h3><a href="{{ post.url }}">{{ post.title }}</a></h3>
|
||
<span class="post-date">{{ post.date | date_to_string }}</span>
|
||
<p>{{ post.description | truncatewords: 100 }}</p>
|
||
</li>
|
||
{% endfor %}
|
||
</ul>
|
||
|
||
## Changelog
|
||
|
||
<ul>
|
||
{% for post in site.categories.changelog %}
|
||
<li>
|
||
<h3><a href="{{ post.url }}">{{ post.title }}</a></h3>
|
||
<span class="post-date">{{ post.date | date_to_string }}</span>
|
||
<p>{{ post.description | truncatewords: 100 }}</p>
|
||
</li>
|
||
{% endfor %}
|
||
</ul>
|