diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org index c5ce9ee3f..45f67166d 100644 --- a/CONTRIBUTING.org +++ b/CONTRIBUTING.org @@ -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