spacemacs/doc/CONTRIBUTE.org

* Contribute to Spacemacs

** Table of Contents                                                 :TOC@4:
 - [[#contribute-to-spacemacs][Contribute to Spacemacs]]
   - [[#pull-request-guidelines][Pull Request Guidelines]]
     - [[#ideally-and-for-simple-prs][Ideally and for /simple/ PRs:]]
     - [[#for-complex-pull-requests][For complex pull requests:]]
     - [[#getting-help][Getting Help]]
   - [[#submitting-a-configuration-layer][Submitting a configuration layer]]
   - [[#testing][Testing]]
   - [[#submitting-a-banner][Submitting a banner]]
   - [[#credits][Credits]]
     - [[#license][License]]
     - [[#file-header][File header]]
     - [[#author-of-a-contribution-layer][Author of a contribution layer]]
     - [[#contributor-of-a-contribution-layer][Contributor of a contribution layer]]

** Pull Request Guidelines
=Spacemacs= branch 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.

/PR = pull request/

*** Ideally and for /simple/ PRs:
-  branch from =develop=
-  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 /fast-forwarded/ whenever it's possible and
/cherry-picked/ otherwise (most likely they will be cherry-picked).

*** For complex pull requests:
-  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/.

*** Getting Help
If you have any question on this process, join the [[https://gitter.im/syl20bnr/spacemacs][gitter
chatroom]] and ask your questions there. It will be a pleasure to help you to
contribute!

** Submitting a configuration layer
Contributed configuration layers are stored in the =layers= folder. The
=layers= folder also contains categories prefixed with =+= to put your
layers in. For example a layer for a language would go in the
=layers/+lang= folder.

It is recommended to join a =README.org= file with your layer:
  - ideally this file should document the packages of your layer as well as the
    key bindings associated with them
  - a template is provided in =~/.emacs.d/core/templates/layer-README.template=,
    use it as much as possible
  - another good practice is to start from the =README.org= of an existing layer
  - if a logo exists for the layer you can add it at the top of the =README.org=
    before the TOC. The maximum recommended height is 200 pixels.

Please read the [[LAYERS.org][tips for writing layers]] first.

** 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).

Spacemacs uses Travis CI to perform more comprehensive testing, where each
testable layer is enabled in turn.

To add tests for a layer, do the following:

1. Create a subfolder of =tests= corresponding to the layer you want to test.
2. Write a file called =dotspacemacs.el= in that folder. It should be a minimal
   dotfile that enables the layer in question (and other layers it may depend
   on).
3. Write a number of files with tests. Please try to separate unit and
   functional tests. Look at existing tests for clues.
4. Write a =Makefile= in that folder. It should define three variables.
   - =LOAD_FILES= :: a list of additional files to load before testing (relative
                     to the root Spacemacs folder). This should typically be
                     =init.el=.
   - =UNIT_TEST_FILES= :: a list of unit test files in the current folder.
   - =FUNC_TEST_FILES= :: a list of functional test files in the current folder.
   See existing tests for examples.
   #+begin_src makefile
   TEST_DIR := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))

   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.

** Submitting a banner
The startup banner is by default 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 width size
should be around 75 characters.

** Credits
*** License
The license is GPLv3 for all parts specific to =Spacemacs=, this
includes: - the initialization and core files - 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.

*** File header
Template:

#+BEGIN_EXAMPLE
    ;;; extensions.el --- NAME Layer extensions File for Spacemacs
    ;;
    ;; Copyright (c) 2012-2014 Sylvain Benner
    ;; Copyright (c) 2014-2015 Sylvain Benner & Contributors
    ;;
    ;; Author: Sylvain Benner <sylvain.benner@gmail.com>
    ;; URL: https://github.com/syl20bnr/spacemacs
    ;;
    ;; This file is not part of GNU Emacs.
    ;;
    ;;; License: GPLv3
#+END_EXAMPLE

*** Author of a contribution layer
In the file header: - change =NAME= to the name of the layer, - change
the default author name =Sylvain Benner= to your name, - 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, - other lines should not be modified

*** Contributor of a contribution layer
You should not modify any header file. A very cool way to show your
contributions will be available in Spacemacs at some point, /Stay
Tuned/.