Update CONTRIBUTING.org
This commit is contained in:
parent
315528c89f
commit
3a9a130e4a
|
@ -25,7 +25,6 @@ Thanks! :heart: :heart: :heart:
|
||||||
- [[#credits][Credits]]
|
- [[#credits][Credits]]
|
||||||
|
|
||||||
* Asking for help
|
* Asking for help
|
||||||
|
|
||||||
If you want to ask an usage question, be sure to look first into some places as
|
If you want to ask an usage question, be sure to look first into some places as
|
||||||
it may hold the answer:
|
it may hold the answer:
|
||||||
|
|
||||||
|
@ -38,7 +37,6 @@ discuss it with us :relaxed:. We will direct you to a solution, or ask you to
|
||||||
open an issue if it is needed.
|
open an issue if it is needed.
|
||||||
|
|
||||||
* Reporting issues
|
* Reporting issues
|
||||||
|
|
||||||
Issues have to be reported on our [[https://github.com/syl20bnr/spacemacs/issues][issues tracker]]. Please:
|
Issues have to be reported on our [[https://github.com/syl20bnr/spacemacs/issues][issues tracker]]. Please:
|
||||||
|
|
||||||
- Check that the issue has not already been reported.
|
- Check that the issue has not already been reported.
|
||||||
|
@ -49,7 +47,7 @@ Issues have to be reported on our [[https://github.com/syl20bnr/spacemacs/issues
|
||||||
it has been changed/corrected.
|
it has been changed/corrected.
|
||||||
- Try to use a clear title, and describe your problem with complete sentences.
|
- Try to use a clear title, and describe your problem with complete sentences.
|
||||||
- Include the following information in your issue:
|
- Include the following information in your issue:
|
||||||
- The output of =SPC h d s= (=M-m h d s= for emacs mode), which gives the
|
- The output of =SPC h d s= (=M-m h d s= in Emacs style), which gives the
|
||||||
versions information about your installation.
|
versions information about your installation.
|
||||||
- If relevant, include the mode in which the problem arise (e.g. javascript
|
- If relevant, include the mode in which the problem arise (e.g. javascript
|
||||||
files, =org-mode=, etc…).
|
files, =org-mode=, etc…).
|
||||||
|
@ -57,7 +55,6 @@ Issues have to be reported on our [[https://github.com/syl20bnr/spacemacs/issues
|
||||||
step guide.
|
step guide.
|
||||||
|
|
||||||
* Contributing code
|
* Contributing code
|
||||||
|
|
||||||
Code contributions are welcome. Please read the following sections carefully. In
|
Code contributions are welcome. Please read the following sections carefully. In
|
||||||
any case, feel free to join us on the [[https://gitter.im/syl20bnr/spacemacs][gitter chat]] to ask questions about
|
any case, feel free to join us on the [[https://gitter.im/syl20bnr/spacemacs][gitter chat]] to ask questions about
|
||||||
contributing!
|
contributing!
|
||||||
|
@ -70,8 +67,8 @@ The license is =GPLv3= for all parts specific to Spacemacs, this includes:
|
||||||
- All the layer files.
|
- All the layer files.
|
||||||
|
|
||||||
For files not belonging to Spacemacs like extensions and libraries, refer to the
|
For files not belonging to Spacemacs like extensions and libraries, refer to the
|
||||||
header file. Those files should not have an empty header, please report any file
|
header file. Those files should not have an empty header, we may not accept
|
||||||
imported in Spacemacs without a proper header.
|
code without a proper header file.
|
||||||
|
|
||||||
*** Conventions
|
*** Conventions
|
||||||
Spacemacs is based on conventions, mainly for naming functions, keybindings
|
Spacemacs is based on conventions, mainly for naming functions, keybindings
|
||||||
|
@ -79,9 +76,9 @@ definition and writing documentation. Please read the [[doc/CONVENTIONS.org][CON
|
||||||
before your first contribution to get to know them.
|
before your first contribution to get to know them.
|
||||||
|
|
||||||
*** Pull-Request
|
*** Pull-Request
|
||||||
Spacemacs branching model is inspired from the [[http://nvie.com/posts/a-successful-git-branching-model/][git-flow]] model: You'll have to
|
Submit your contribution against the =develop= branch. You should not use
|
||||||
submit your contributions and fixes within a Pull-Request to apply against the
|
your =master= branch to modify Spacemacs, this branch is considered to be
|
||||||
=develop= branch.
|
read-only.
|
||||||
|
|
||||||
/PR = Pull-Request/
|
/PR = Pull-Request/
|
||||||
|
|
||||||
|
@ -104,24 +101,20 @@ Those PRs are usually /cherry-picked/.
|
||||||
Those PRs are /merged/ and explicitly /not fast-forwarded/.
|
Those PRs are /merged/ and explicitly /not fast-forwarded/.
|
||||||
|
|
||||||
*** Commit messages
|
*** Commit messages
|
||||||
|
Write commit messages according to adapted [[http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html][Tim Pope's guidelines]]:
|
||||||
|
|
||||||
Write commit messages according to [[http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html][Tim Pope's guidelines]]. In short:
|
- Use present tense and write in the imperative: “Fix bug”, not “fixed bug” or
|
||||||
|
“fixes bug”.
|
||||||
- Start with a capitalized, short (50 characters or less) summary, followed by a
|
- Start with a capitalized, short (72 characters or less) summary, followed by a
|
||||||
blank line.
|
blank line.
|
||||||
- If necessary, add one or more paragraphs with details, wrapped at 72
|
- If necessary, add one or more paragraphs with details, wrapped at 72
|
||||||
characters.
|
characters.
|
||||||
- Use present tense and write in the imperative: “Fix bug”, not “fixed bug” or
|
|
||||||
“fixes bug”.
|
|
||||||
- Separate paragraphs by blank lines.
|
- Separate paragraphs by blank lines.
|
||||||
- Do *not* use special markup (e.g. Markdown). Commit messages are plain text.
|
|
||||||
You may use `*emphasis*` or `_underline_` though, following conventions
|
|
||||||
established on mailing lists.
|
|
||||||
|
|
||||||
This is a model commit message:
|
This is a model commit message:
|
||||||
|
|
||||||
#+begin_EXAMPLE
|
#+begin_EXAMPLE
|
||||||
Capitalized, short (50 chars or less) summary
|
Capitalized, short (72 chars or less) summary
|
||||||
|
|
||||||
More detailed explanatory text, if necessary. Wrap it to about 72
|
More detailed explanatory text, if necessary. Wrap it to about 72
|
||||||
characters or so. In some contexts, the first line is treated as the
|
characters or so. In some contexts, the first line is treated as the
|
||||||
|
@ -148,7 +141,6 @@ Further paragraphs come after blank lines.
|
||||||
to comply to these guidelines.
|
to comply to these guidelines.
|
||||||
|
|
||||||
** Contributing a layer
|
** Contributing a layer
|
||||||
|
|
||||||
Please read the [[file:doc/LAYERS.org][layers documentation]] first.
|
Please read the [[file:doc/LAYERS.org][layers documentation]] first.
|
||||||
|
|
||||||
It is recommended to use the =configuration-layer/create-layer= command in order
|
It is recommended to use the =configuration-layer/create-layer= command in order
|
||||||
|
@ -182,15 +174,11 @@ template inside =core/templates/=, so look in there first. Note that if you use
|
||||||
=configuration-layer/create-layer=, spacemacs will prepare files and headers for
|
=configuration-layer/create-layer=, spacemacs will prepare files and headers for
|
||||||
you, and for free :smile: !
|
you, and for free :smile: !
|
||||||
|
|
||||||
*** Author of a contribution layer
|
*** Author of a new layer
|
||||||
In the files header:
|
In the files header, change the default author name (=Sylvain Benner=) to your
|
||||||
- Do not remove the line: =;; Copyright (c) 2012-2014 Sylvain Benner=,
|
name.
|
||||||
- Modify the second copyright line by replacing the default name and dates,
|
|
||||||
*keep* =& Contributors= in this line,
|
|
||||||
- Change the default author name (=Sylvain Benner=) to your name,
|
|
||||||
- Other lines should not be modified
|
|
||||||
|
|
||||||
*** Contributor of a contribution layer
|
*** Contributor to an existing layer
|
||||||
If you are contributing to an already existing layer, you should not modify any
|
If you are contributing to an already existing layer, you should not modify any
|
||||||
header file.
|
header file.
|
||||||
|
|
||||||
|
@ -199,20 +187,21 @@ Keybindings are an important part of spacemacs.
|
||||||
|
|
||||||
First if you want to have some personal keybindings, you can freely bind them
|
First if you want to have some personal keybindings, you can freely bind them
|
||||||
inside the ~SPC o~ and ~SPC m o~ prefixes which are reserved for the user. This
|
inside the ~SPC o~ and ~SPC m o~ prefixes which are reserved for the user. This
|
||||||
can be done from the =dotspacemacs/user-config= function of you =.spacemacs= and
|
can be done from the =dotspacemacs/user-config= function of your =.spacemacs=
|
||||||
don't require any contribution to Spacemacs.
|
file and don't require any contribution to Spacemacs.
|
||||||
|
|
||||||
If you think there are important functions without keybindings, and they should
|
If you think it worth contributing a new key bindings then be sure to read
|
||||||
be part of Spacemacs, then first read the [[doc/CONVENTIONS.org][CONVENTIONS.org]] file to find the best
|
the [[doc/CONVENTIONS.org][CONVENTIONS.org]] file to find the best key bindings, then create a
|
||||||
keybindings, then create a Pull-Request with your changes.
|
Pull-Request with your changes.
|
||||||
|
|
||||||
*ALWAYS* document your new keybindings or keybindings changes inside the
|
*ALWAYS* document your new keybindings or keybindings changes inside the
|
||||||
relevant documentation file. It should be the layer's =README.org= file for
|
relevant documentation file. It should be the layer's =README.org= file for
|
||||||
layer's keybindings, or =DOCUMENTATION.org= for general Spacemacs ones.
|
layer's keybindings, or =DOCUMENTATION.org= for general Spacemacs key
|
||||||
|
bindings.
|
||||||
|
|
||||||
** Contributing a banner
|
** Contributing a banner
|
||||||
The startup banner is by default randomly chosen among a pool of banners each
|
The startup banner is by default the Spacemacs logo but there are also ASCII
|
||||||
time Spacemacs starts. Banners are located in the directory =core/banners/=.
|
banners available in the directory =core/banners/=.
|
||||||
|
|
||||||
If you have some ASCII skills you can submit your artwork!
|
If you have some ASCII skills you can submit your artwork!
|
||||||
|
|
||||||
|
@ -220,15 +209,11 @@ You are free to choose a reasonable height size but the width size should be
|
||||||
around 75 characters.
|
around 75 characters.
|
||||||
|
|
||||||
* Additional information
|
* Additional information
|
||||||
|
|
||||||
** Testing
|
** Testing
|
||||||
Tests live in the =tests/= folder, with a folder structure corresponding to the
|
Tests live in the =tests/= folder, with a folder structure corresponding to the
|
||||||
rest of the repository.
|
rest of the repository.
|
||||||
|
|
||||||
To run tests locally, navigate to the relevant subfolder and run =make=. The
|
To run tests locally, navigate to the relevant subfolder and run =make=.
|
||||||
tests will be run with your own personal dotfile, so you should not expect tests
|
|
||||||
to succeed if you have personal configuration that will make them fail (such as
|
|
||||||
not having enabled a layer).
|
|
||||||
|
|
||||||
Spacemacs uses Travis CI to perform more comprehensive testing, where each
|
Spacemacs uses Travis CI to perform more comprehensive testing, where each
|
||||||
testable layer is enabled in turn.
|
testable layer is enabled in turn.
|
||||||
|
@ -250,15 +235,14 @@ To add tests for a layer, do the following:
|
||||||
#+begin_src makefile
|
#+begin_src makefile
|
||||||
TEST_DIR := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
|
TEST_DIR := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
|
||||||
|
|
||||||
LOAD_FILES = ... UNIT_TEST_FILES = ... FUNC_TEST_FILES = ...
|
LOAD_FILES = ...
|
||||||
|
UNIT_TEST_FILES = ...
|
||||||
|
FUNC_TEST_FILES = ...
|
||||||
|
|
||||||
include ../../spacemacs.mk
|
include ../../spacemacs.mk
|
||||||
#+end_src
|
#+end_src
|
||||||
|
|
||||||
5. Add the new test to list of tests in =travis/run_build.sh=.
|
5. Add the new test to list of tests in =travis/run_build.sh=.
|
||||||
|
|
||||||
Spacemacs is lacking tests, so contributions are welcome.
|
|
||||||
|
|
||||||
* Credits
|
* Credits
|
||||||
|
|
||||||
This =CONTRIBUTING.org= file is partially based on the [[https://github.com/rails/rails/blob/master/CONTRIBUTING.md][Rails Contribution
|
This =CONTRIBUTING.org= file is partially based on the [[https://github.com/rails/rails/blob/master/CONTRIBUTING.md][Rails Contribution
|
||||||
|
|
Loading…
Reference in New Issue