Table of Contents

Contribution guidelines

Table of ContentsClose

Spacemacs is a volunteer effort. We encourage you to pitch in. The community makes Spacemacs what it is. We have a few guidelines, which we ask all contributors to follow.

You can only consider reading the sections relevant to what you are going to do or just watch this video here:

Thanks! :heart: :heart: :heart:

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

If your question is not answered there, then please come into our gitter chat to discuss it with us :relaxed:. We will direct you to a solution, or ask you to open an issue if it is needed.

2. Reporting issues

Issues have to be reported on our issues tracker. Please:

  • Check that the issue has not already been reported.
  • Check that the issue has not been fixed in the develop version of Spacemacs.
    • This can be achieved by running Spacemacs on the develop branch and trying to reproduce the bug here. You can also check at the source code to see if it has been changed/corrected.
  • Try to use a clear title, and describe your problem with complete sentences. See also How to make a great bug report in the wiki.
  • Include the following information in your issue:
    • 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…).
    • If possible, try to include details on how to reproduce it, like a step by step guide.

3. Contributing code

Code contributions are welcome. Please read the following sections carefully. In any case, feel free to join us on the gitter chat to ask questions about contributing!

3.1. General contribution guidelines

3.1.1. 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 local packages and libraries, refer to the header file. Those files should not have an empty header, we may not accept code without a proper header file.

3.1.2. Conventions

Spacemacs is based on conventions, mainly for naming functions, keybindings definition and writing documentation. Please read the CONVENTIONS.org file before your first contribution to get to know them.

3.1.3. Changelog entry

Add a short entry describing your proposed change under a suitable subheading in CHANGELOG.develop. Use the previous entries and commit messages instructions as guidelines. You can add your name or github username in parentheses at the end of the entry if you want to. If an entry already exists describing your PR (small documentation improvements etc.), you can omit the changelog entry or add your name at the end of the pre-existing one.

3.1.4. Pull Request

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.

You may want to read our beginner's guide for Pull Requests.

PR = Pull Request

3.1.4.1. Ideally for simple PRs (most of them):
  • 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 (here's a guide)
  • Rebase your PR branch on top of upstream develop before submitting the PR

Those PRs are usually cherry-picked.

3.1.4.2. For complex PRs (big refactoring, etc):
  • 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.

3.1.5. Commit messages

Write commit messages according to adapted Tim Pope's guidelines:

  • 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.
  • Separate paragraphs by blank lines.

This is a model commit message: 

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
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

    - Typically a hyphen or asterisk is used for the bullet, followed by a
      single space, with blank lines in between, but conventions vary here

    - Use a hanging indent

Git Commit and Magit provide Emacs mode for Git commit messages, which helps you to comply to these guidelines.

3.2. Contributing a layer

Please read the layers documentation first.

It is recommended to use the configuration-layer/create-layer command in order to create a layer, as it will take care of using the files templates and will also create the file headers correctly.

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.

Layer with no associated configuration will be rejected. For instance a layer with just a package and a hook can be easily replaced by the usage of the variable dotspacemacs-additional-packages.

3.2.1. File header

The file header for elisp files should look like the following template: 


;;; FILENAME --- NAME Layer <TYPE> File for Spacemacs
;;
;; Copyright (c) 2012-<YEAR> Sylvain Benner & Contributors
;;
;; Author: YOUR_NAME <YOUR_EMAIL>
;; URL: https://github.com/syl20bnr/spacemacs
;;
;; This file is not part of GNU Emacs.
;;
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <http://www.gnu.org/licenses/>.

You should replace FILENAME by the name of the file (e.g. packages.el), and NAME by the name of the layer you are creating. TYPE should match the FILENAME (e.g. funcs for funcs.el). Don't forget to replace YEAR, YOUR_NAME, and YOUR_EMAIL also. Some files already have a 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: !

3.2.2. Author of a new layer

In the files header, change the default author name (Sylvain Benner) to your name.

3.2.2.1. README.org tags

Every README.org file of a layer should have #+TAGS: line: 

#+TITLE: My layer

#+TAGS: layer|web service

* Table of Contents                     :TOC_5_gh:noexport:
...

Individual tags are separated with "|" character. Example above has 2 tags: "layer" and "web service". Tags are listed in <spacemacsroot>/.ci/spacedoc-cfg.edn configuration file. 

:spacetools.spacedoc.config/valid-tags
{"chat" "Chats"
...
 <TAG> <LABEL>
...
 "completion" "Completion"}

Labels are used to name headlines in LAYERS.org file and :spacetools.spacedoc.config/layers-org-query defines structure of the file by chaining tags into a tree where every leaf turns into a list of descriptions pulled out of README.org files which tags match leaf's path in the tree. You can see how the shape of <spacemacsroot>/.ci/spacedoc-cfg.edn repeats in TOC of LAYERS.org.

Important details:

If you want to experiment with the tool locally: 

docker run --rm \
  -v <SPACEMACS_REPO_ROOT>:/tmp/docs \
  -v <PATH_TO_CONFIG_FILE>:/opt/spacetools/spacedoc-cfg.edn \
  jare/spacetools docfmt /tmp/docs/

3.2.3. Contributor to an existing layer

If you are contributing to an already existing layer, you should not modify any header file.

3.3. Contributing a key binding

Key bindings are an important part of Spacemacs.

First if you want to have some personal key bindings, 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 your .spacemacs file and don't require any contribution to Spacemacs.

If you think it worth contributing a new key bindings then be sure to read the CONVENTIONS.org file to find the best key bindings, then create a PR with your changes.

ALWAYS document your new key bindings or key bindings changes inside the relevant documentation file. It should be the layer's README.org file for layer's key bindings, or DOCUMENTATION.org for general Spacemacs key bindings.

3.4. Contributing a banner

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!

You are free to choose a reasonable height size but the width size should be around 75 characters.

4. Reviewing Pull Requests

You can contribute by reviewing PRs created by others. This will help share the workload of the project maintainers by letting them know that a PR has been tested by an independent reviewer. The steps:

  • Check that the PR complies with the guidelines in Contributing code.
  • Check that the PR complies with CONVENTIONS.org.
  • Check out the PR branch and test it. Remember to update your packages and your ~/.spacemacs file. Testing means that you actually use the features touched by the PR, and the more complex or feature-rich the proposed changes are, the more testing is required. Be creative in trying to find bugs! Preferably, use the PR branch for hours or days to help stumble on unforeseen issues. Of course, common sense can be used and typo fixes do not need to be tested against bugs, but be thorough in actual code changes. Testing with a fresh Spacemacs installation might be a good idea as well.
  • Step back and think if the proposed changes could cause any other problems not covered by your testing. You should also ask yourself whether or not you feel that your testing is adequate to confidently state that this PR introduces no new bugs. If you feel that additional testing by more community members could be helpful, state so in your review.

If you find something to improve, report it constructively and politely so the contributor can update the PR accordingly. When you find that the PR is ready to merge, you can leave an approving review. Please report explicitly how you tested the PR for bugs, and confirm that you have checked its compliance with the code conventions. Copy the following line to your approving review to notify the collaborators: 

Ready to be merged! (@syl20bnr @TheBB @d12frosted @bmag @JAremko)

Now the collaborators who have write access to the repository will use their judgement to either merge the PR or require further review from another reviewer. This is done to ensure a thorough cross-referencing in case of complex changes, your review is very valuable in these cases as well!

4.1. Using Magit to quickly test PRs

It is possible to manage PRs directly inside the Magit status buffer SPC g s. First add the github layer to your dotfile which will pull the package forge. Once installed you need to set it up with a GitHub personal access token after which you can execute M-x forge-pull. It will fetch all the PRs which may take a few seconds as we have lot of PRs. Note also that all your Magit actions will get some additional delay due to the refresh of the PRs list.

Now, from the Magit status buffer you can:

  • checkout a PR with b y and searching it by name or ID
  • donate all commits to develop by doing A d and selecting your current branch first and the develop branch second
  • switch to the develop branch by pressing b b and selecting it
  • delete the PR branch and remote by doing b x and selecting it

5. Additional information

5.1. 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.

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.

    • a list of additional files to load before testing (relative to the root Spacemacs folder). This should typically be init.el.
    • a list of unit test files in the current folder.
    • 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
  5. Add the new test to list of tests in travis/run_build.sh.

6. Credits

This CONTRIBUTING.org file is partially based on the Rails Contribution guidelines and Flycheck Contribution guidelines.

Author: root

Created: 2024-04-03 Wed 19:39

Validate