mirror of
https://github.com/SpaceVim/SpaceVim.git
synced 2025-02-02 20:30:05 +08:00
Async with development.md
This commit is contained in:
wsdjeg
parent
b40cad8c94
commit
2cfcbec722
215
CONTRIBUTING.md
215
CONTRIBUTING.md
@ -1 +1,216 @@
|
||||
# Contributing guide
|
||||
|
||||
SpaceVim is a 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 ask all contributors to follow.
|
||||
|
||||
You can only consider reading the sections 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.
|
||||
- [Reporting issues](#reporting-issues) if you are about to open a new issue.
|
||||
- [Contributing code](#contributing-code) if you are about to send a Pull-Request.
|
||||
|
||||
### 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:
|
||||
- <kbd>:h SpaceVim-faq</kbd>: Some of the most frequently asked questions are answered there.
|
||||
- [SpaceVim documentation](https://spacevim.org/documentation): It is the general documentation of SpaceVim.
|
||||
|
||||
### Reporting issues
|
||||
|
||||
issues have to be reported on [issues tracker](https://github.com/SpaceVim/SpaceVim/issues), Please:
|
||||
- Check that there is no duplicate issue in the issues tracker, you can search keywords in the issues tracker.
|
||||
- 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 and follow the issue template.
|
||||
- Include details on how to reproduce it, just like a step by step guide.
|
||||
|
||||
### Contributing code
|
||||
|
||||
Code contributions are welcome. Please read the following sections carefully. In any case, feel free to join us on the [gitter chat](https://gitter.im/SpaceVim/SpaceVim) to ask questions about contributing!
|
||||
|
||||
#### License
|
||||
|
||||
The license is MIT for all the parts of SpaceVim. this includes:
|
||||
- The initialization and core files
|
||||
- All the layer files.
|
||||
|
||||
For files not belonging to Spacemacs 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](https://spacevim.org/development/conventions) before your first contribution to get to know them.
|
||||
|
||||
#### Pull Request
|
||||
|
||||
Submit your contribution against the `dev` branch. You should not use your master branch to modify SpaceVim, this branch is considered to be read-only.
|
||||
|
||||
You may want to read our beginner’s guide for Pull Requests.
|
||||
|
||||
PR = Pull-Request
|
||||
|
||||
##### Ideally for simple PRs (most of them):
|
||||
|
||||
- Branch from `dev`
|
||||
- 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
|
||||
- Rebase your PR branch on top of upstream develop before submitting the PR
|
||||
|
||||
Those PRs are usually cherry-picked.
|
||||
|
||||
##### For complex PRs (big refactoring, etc):
|
||||
|
||||
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.
|
||||
Commit messages
|
||||
|
||||
Write commit messages according to adapted [Tim Pope’s guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html):
|
||||
|
||||
- Use present tense and write in the imperative: “Fix bug”, not “fixed bug” or “fixes bug”.
|
||||
- Start with a capitalized, short (72 characters or less) summary, followed by a blank line.
|
||||
- If necessary, add one or more paragraphs with details, wrapped at 72 characters.
|
||||
- Separate paragraphs by blank lines.
|
||||
|
||||
This is a model commit message:
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
[Gita] provide vim mode for Git commit messages, which helps you to comply to these guidelines.
|
||||
|
||||
#### 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 `g:spacevim_custom_plugins`.
|
||||
|
||||
##### File header
|
||||
|
||||
The file header for vim script should look like the following template:
|
||||
|
||||
```viml
|
||||
"=============================================================================
|
||||
" FILENAME --- NAME layer file for SpaceVim
|
||||
" Copyright (c) 2012-2016 Shidong Wang & Contributors
|
||||
" Author: YOUR_NAME <YOUR_EMAIL>
|
||||
" URL: https://spacevim.org
|
||||
" License: MIT license
|
||||
"=============================================================================
|
||||
```
|
||||
|
||||
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 also.
|
||||
|
||||
##### Author of a new layer
|
||||
|
||||
In the files header, change the default author name (Shidong Wang) to your name.
|
||||
|
||||
here is an example for creating a new layer names `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: MIT license
|
||||
"=============================================================================
|
||||
|
||||
""
|
||||
" @section foo, layer-foo
|
||||
" @parentsection layers
|
||||
" This the doc for this layer:
|
||||
"
|
||||
" @subsection Mappings
|
||||
" >
|
||||
" Mode Key Function
|
||||
" -------------------------------------------------------------
|
||||
" normal <leader>jA generate accessors
|
||||
" normal <leader>js generate setter accessor
|
||||
" <
|
||||
" @subsection options
|
||||
" >
|
||||
" Name Description Default
|
||||
" -------------------------------------------------------------
|
||||
" g:foo_option1 Set option1 for foo layer 1
|
||||
" g:foo_option2 Set option2 for foo layer 2
|
||||
" g:foo_option3 Set option3 for foo layer 3
|
||||
" <
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
4. send PR to SpaceVim.
|
||||
|
||||
##### Contributor to an existing layer
|
||||
|
||||
If you are contributing 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 `~/.SpaceVim.d/init.vim` file.
|
||||
|
||||
If you think it worth contributing a new mappings then be sure to read the documentation to find the best mappings, then create a Pull-Request with your changes.
|
||||
|
||||
ALWAYS document your new mappings or mappings changes inside the relevant documentation file. It should be the the layer file and the [documentation.md](https://spacevim.org/documentation).
|
||||
|
||||
#### 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 provide a lot of public [APIs](https://spacevim.org/apis), you can create plugins base on this APIs. also you can add a badge to the README.md of your plugin.
|
||||
|
||||
|
||||
|
||||
markdown
|
||||
|
||||
```md
|
||||
[](https://spacevim.org)
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user