2014-11-04 02:56:35 +00:00
|
|
|
# Contribute to Spacemacs
|
|
|
|
|
|
|
|
|
|
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc/generate-toc again -->
|
|
|
|
|
**Table of Contents**
|
|
|
|
|
|
|
|
|
|
- [Contribute to Spacemacs](#contribute-to-spacemacs)
|
|
|
|
|
- [Pull Request Guidelines](#pull-request-guidelines)
|
2015-01-10 04:32:27 +00:00
|
|
|
- [Submitting a configuration layer](#submitting-a-configuration-layer)
|
|
|
|
|
- [Configuration layer template](#configuration-layer-template)
|
2014-12-25 20:25:34 +00:00
|
|
|
- [Submitting a banner](#submitting-a-banner)
|
2014-11-04 02:56:35 +00:00
|
|
|
|
|
|
|
|
<!-- markdown-toc end -->
|
|
|
|
|
|
|
|
|
|
## Pull Request Guidelines
|
|
|
|
|
|
2014-11-15 03:30:22 +00:00
|
|
|
`Spacemacs` branch model is inspired from the [git-flow][] model: You'll have
|
|
|
|
|
to submit your contributions and fixes within a pull-request to apply against
|
|
|
|
|
the `develop` branch.
|
2014-11-04 02:56:35 +00:00
|
|
|
|
|
|
|
|
_PR = pull request_
|
|
|
|
|
|
|
|
|
|
**Guidelines:**
|
2014-11-04 16:35:07 +00:00
|
|
|
|
|
|
|
|
1) Ideally and for simple PRs:
|
|
|
|
|
|
2014-11-04 02:56:35 +00:00
|
|
|
- branch from `develop` only
|
|
|
|
|
- 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
|
2014-11-04 16:35:07 +00:00
|
|
|
|
2014-11-11 05:18:43 +00:00
|
|
|
Those PRs are _fast-forwarded_ whenever it's possible and _cherry-picked_
|
|
|
|
|
otherwise.
|
2014-11-04 16:35:07 +00:00
|
|
|
|
|
|
|
|
2) For complex pull requests:
|
|
|
|
|
|
|
|
|
|
- squash only the commits with uninteresting changes like typos, syntax fixes,
|
|
|
|
|
etc... and keep the important steps in different commits.
|
|
|
|
|
|
2014-11-11 05:18:43 +00:00
|
|
|
Those PRs are _merged_.
|
2014-11-04 02:56:35 +00:00
|
|
|
|
|
|
|
|
**Getting Help:**
|
|
|
|
|
If you have any question on this process, join the [gitter chatroom][gitter]
|
2014-11-15 03:30:22 +00:00
|
|
|
and ask your questions there. It will be a pleasure to help you to contribute!
|
2014-11-04 02:56:35 +00:00
|
|
|
|
2015-01-10 04:32:27 +00:00
|
|
|
## Submitting a configuration layer
|
|
|
|
|
|
|
|
|
|
Contributed configuration layers are stored in the `contrib` folder. If the
|
|
|
|
|
layer is about a programming language or script then it must be added to
|
|
|
|
|
`contrib/lang` folder.
|
2014-11-04 02:56:35 +00:00
|
|
|
|
|
|
|
|
It is recommended to join a `README.md` file with your layer, ideally this file
|
|
|
|
|
should document the packages of your layer as well as the key bindings
|
2014-12-25 20:25:34 +00:00
|
|
|
associated with them.
|
2014-11-04 02:56:35 +00:00
|
|
|
|
2015-01-10 04:32:27 +00:00
|
|
|
Add a TOC at the start of the file with the command `markdown-toc/generate-toc`.
|
|
|
|
|
|
|
|
|
|
If a logo exists for the layer you can add it at the top of the `README.md`
|
|
|
|
|
before the TOC. The maximum recommended height is 200 pixels.
|
|
|
|
|
|
|
|
|
|
### Configuration layer template
|
|
|
|
|
|
2014-12-25 20:25:34 +00:00
|
|
|
You will find a template in `~/.emacs.d/core/templates/layer-README.template`.
|
2014-11-04 02:56:35 +00:00
|
|
|
|
2014-12-25 20:25:34 +00:00
|
|
|
Another good practice is to start from the `README.md` of an existing layer.
|
|
|
|
|
|
|
|
|
|
## Submitting a banner
|
|
|
|
|
|
|
|
|
|
The startup banner is randomly chosen among a pool of banners each time
|
|
|
|
|
`Spacemacs` starts. Banners are located in directory
|
|
|
|
|
`~/.emacs.d/core/banners`.
|
|
|
|
|
|
|
|
|
|
If you have some ASCII skills you can submit your artwork!
|
|
|
|
|
|
|
|
|
|
You are free to choose a reasonable height size but the recommended width
|
|
|
|
|
size is 75 characters to keep the code simple.
|
2014-11-15 03:30:22 +00:00
|
|
|
|
|
|
|
|
[git-flow]: http://nvie.com/posts/a-successful-git-branching-model/
|
|
|
|
|
[gitter]: https://gitter.im/syl20bnr/spacemacs
|
