spacemacs/doc/CONTRIBUTE.org at 1e290b4282431847b9dc7be0dd9c201c371e3692

Archived

This repository has been archived on 2024-10-22. You can view files and clone it, but cannot push or open issues or pull requests.

justbur 6eab954afe Use + instead of ! for layer categories

Helm seems to treat "!" specially in pattern matching, so having a ! in
the pattern string when traversing directories is problematic. This
change fixes #2737, because as far as I can tell "+" has no special
meaning in a helm pattern.

Of course, we can choose a different character, but I'm fond of "+" as
representing "more layers here".

2015-09-11 00:13:51 -04:00

6.1 KiB

Raw Blame History

Contribute to Spacemacs

Contribute to Spacemacs

Table of Contents TOC@4

Contribute to Spacemacs

Pull Request Guidelines

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.

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 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 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:

Create a subfolder of tests corresponding to the layer you want to test.
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).
Write a number of files with tests. Please try to separate unit and functional tests. Look at existing tests for clues.
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.
```
TEST_DIR := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))

LOAD_FILES = ...
UNIT_TEST_FILES = ...
FUNC_TEST_FILES = ...

include ../../spacemacs.mk
```
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:

    ;;; 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

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.

6.1 KiB Raw Blame History