Update CONTRIBUTING.org
This commit is contained in:
syl20bnr
parent
315528c89f
commit
3a9a130e4a
|
|
@ -25,7 +25,6 @@ Thanks! :heart: :heart: :heart:
|
|||
- [[#credits][Credits]]
|
||||
|
||||
* Asking for help
|
||||
|
||||
If you want to ask an usage question, be sure to look first into some places as
|
||||
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.
|
||||
|
||||
* Reporting issues
|
||||
|
||||
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.
|
||||
|
|
@ -49,7 +47,7 @@ Issues have to be reported on our [[https://github.com/syl20bnr/spacemacs/issues
|
|||
it has been changed/corrected.
|
||||
- Try to use a clear title, and describe your problem with complete sentences.
|
||||
- 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.
|
||||
- If relevant, include the mode in which the problem arise (e.g. javascript
|
||||
files, =org-mode=, etc…).
|
||||
|
|
@ -57,7 +55,6 @@ Issues have to be reported on our [[https://github.com/syl20bnr/spacemacs/issues
|
|||
step guide.
|
||||
|
||||
* Contributing code
|
||||
|
||||
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
|
||||
contributing!
|
||||
|
|
@ -70,8 +67,8 @@ The license is =GPLv3= for all parts specific to Spacemacs, this includes:
|
|||
- All the layer files.
|
||||
|
||||
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
|
||||
imported in Spacemacs without a proper header.
|
||||
header file. Those files should not have an empty header, we may not accept
|
||||
code without a proper header file.
|
||||
|
||||
*** Conventions
|
||||
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.
|
||||
|
||||
*** 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 contributions and fixes within a Pull-Request to apply against the
|
||||
=develop= branch.
|
||||
Submit your contribution against the =develop= branch. You should not use
|
||||
your =master= branch to modify Spacemacs, this branch is considered to be
|
||||
read-only.
|
||||
|
||||
/PR = Pull-Request/
|
||||
|
||||
|
|
@ -104,24 +101,20 @@ Those PRs are usually /cherry-picked/.
|
|||
Those PRs are /merged/ and explicitly /not fast-forwarded/.
|
||||
|
||||
*** 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:
|
||||
|
||||
- Start with a capitalized, short (50 characters or less) summary, followed by a
|
||||
- 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.
|
||||
- Use present tense and write in the imperative: “Fix bug”, not “fixed bug” or
|
||||
“fixes bug”.
|
||||
- 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:
|
||||
|
||||
#+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
|
||||
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.
|
||||
|
||||
** Contributing a layer
|
||||
|
||||
Please read the [[file:doc/LAYERS.org][layers documentation]] first.
|
||||
|
||||
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
|
||||
you, and for free :smile: !
|
||||
|
||||
*** Author of a contribution layer
|
||||
In the files header:
|
||||
- Do not remove the line: =;; Copyright (c) 2012-2014 Sylvain Benner=,
|
||||
- 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
|
||||
*** Author of a new layer
|
||||
In the files header, change the default author name (=Sylvain Benner=) to your
|
||||
name.
|
||||
|
||||
*** Contributor of a contribution layer
|
||||
*** Contributor to an existing layer
|
||||
If you are contributing to an already existing layer, you should not modify any
|
||||
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
|
||||
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
|
||||
don't require any contribution to Spacemacs.
|
||||
can be done from the =dotspacemacs/user-config= function of your =.spacemacs=
|
||||
file and don't require any contribution to Spacemacs.
|
||||
|
||||
If you think there are important functions without keybindings, and they should
|
||||
be part of Spacemacs, then first read the [[doc/CONVENTIONS.org][CONVENTIONS.org]] file to find the best
|
||||
keybindings, then create a Pull-Request with your changes.
|
||||
If you think it worth contributing a new key bindings then be sure to read
|
||||
the [[doc/CONVENTIONS.org][CONVENTIONS.org]] file to find the best key bindings, then create a
|
||||
Pull-Request with your changes.
|
||||
|
||||
*ALWAYS* document your new keybindings or keybindings changes inside the
|
||||
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
|
||||
The startup banner is by default randomly chosen among a pool of banners each
|
||||
time Spacemacs starts. Banners are located in the directory =core/banners/=.
|
||||
The startup banner is by default the Spacemacs logo but there are also ASCII
|
||||
banners available in the directory =core/banners/=.
|
||||
|
||||
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.
|
||||
|
||||
* Additional information
|
||||
|
||||
** Testing
|
||||
Tests live in the =tests/= folder, with a folder structure corresponding to the
|
||||
rest of the repository.
|
||||
|
||||
To run tests locally, navigate to the relevant subfolder and run =make=. The
|
||||
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).
|
||||
To run tests locally, navigate to the relevant subfolder and run =make=.
|
||||
|
||||
Spacemacs uses Travis CI to perform more comprehensive testing, where each
|
||||
testable layer is enabled in turn.
|
||||
|
|
@ -250,15 +235,14 @@ To add tests for a layer, do the following:
|
|||
#+begin_src makefile
|
||||
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
|
||||
#+end_src
|
||||
|
||||
5. Add the new test to list of tests in =travis/run_build.sh=.
|
||||
|
||||
Spacemacs is lacking tests, so contributions are welcome.
|
||||
|
||||
* Credits
|
||||
|
||||
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