Spacemacs - raising issues and pull requests
Contributing to Spacemacs is very much a community activity and we can all help the maintainers continue to make Spacemacs an excellent experience for everyone.
With a few simple tips, its easy to report issues and create pull requests that are ready to merge into Spacemacs develop
.
Spacemacs master and develop
If you have a problem with Spacemacs, there is a good chance that its already been fixed in the develop
branch of Spacemacs. Until Spacemacs 0.300 is released to master
then I recommend using the develop
branch. There are lots of new features on develop
too.
To change to develop
, open a terminal and change to the ~/.emacs.d
directory and run the Git command git checkout develop
.
Before starting Emacs with the develop
branch, move your .spacemacs
file to a backup. This will create the latest version of the .spacemacs
file from the Spacemacs template. If you keep your original .spacemacs
file, then use SPC f e D
to launch ediff with your current .spacemacs
file and the latest Spacemacs template.
Updating Spacemacs develop from within Spacemacs demonstrates how to update the
develop
branch using Magit.
Raising Issues
Take a look at the current issue list on the Spacemacs repository before creating a new issue, it might have already been raised. The Spacemacs community is very active, so issues do get raised quickly.
Ask on the Spacemacs Gitter chat if you are not sure if its an issue, or just need help. For Clojure specific help, there is also #spacemacs channel in the Clojurians Slack community.
SPC h I
or M-m h I
within Spacemacs will create an issue on the Spacemacs GitHub repository, including all the useful information about your environment, including version of Spacemacs, Emacs, Operating System, etc. All very useful to help get your issue resolved quicker.
Please be as descriptive as possible on how the issue happens and what you would expect to happen instead.
Making changes
If you have a fix, a new feature or keybindings to add/change, then pull requests are most welcome. Again you can create almost everything from Spacemacs, only visiting GitHub to press the Create pull request button at the end.
Please read the Spacemacs Conventions before making changes, especially the naming and keybinding conventions.
To make a change:
- Update to the latest
develop
branch and fork the project to your own GitHub repository. Or clone Spacemacs to a different directory if you dont want to hack on your live setup. - Create a new branch from
develop
with a meaningful name -SPC g s
to open Magit Status.b c
to start creating a branch. Selectdevelop
from the list of current branches as the base for you new branch. Type in the name of your new branch and pressRET
. You are automatically placed in the new branch. - Make your changes and create a single commit -
SPC g s
for magit status,s
to stage changes,c c
to create a new commit, entering a commit message.
Use the [layer-name] convention if the PR is for a specific layer, to help everyone to find and review your pull request quickly. For example: [Clojure] Sesman and missing eval / format keybindings
Changes in pull requests include three parts and should be all part of a single commit.
- CHANGELOG.develop entry - a summary of the change made that is part of the documentation for the next stable release and so everyone can find it easily
- README.org - any changes to using a layer
- The change itself - unless its just a documentation change in the README.org.
Creating a pull request
An example of making a change to the Clojure layer from within Spacemacs, creating a single commit using Magit.
You only need to visit GitHub to press the Create Pull Request button.
If you need to update a Pull Request, then commit all your changes locally using Commit Amend, c a
in Magit. Then force push
Thank you Practicalli