Newsletter #01: About the 0.200 release

The packages ecosystem moves even faster than Spacemacs and a lot of packages are now incompatible with the version 24.3 of Emacs which has been released in 2013. Supporting this version in Spacemacs is more and more work for maintainers so we decided to drop all the 24.3 related code in Spacemacs effectively raising the minimum Emacs version required to 24.4. We believe that users are able to switch to a newer version of Emacs, if you need help in this process you can try the Gitter chat, I'm sure you'll find solutions there.

We renamed extensions directories in layers to local and the file extensions.el is now ignored, their contents must be moved to the file packages.el and their package declarations must now set the keyword :location to local.

Before:

;; in extensions.el
(setq python-post-extensions
  '(
    nose
    pylookup
    python-compile
    py-yapf
    ))

After:

;; in packages.el
(setq python-packages
  '(
    ;; skipping packages before...
    (nose :location local)
    (pylookup :location local)
    ;; skipping packages after...
    ))

The variables <package>-excluded-packages are now ignored, they have been replaced by the :excluded keyword in <layer>-packages variables.

Before:

(setq vim-empty-lines-packages
      '(
        (vim-empty-lines-mode :location local)
        ))

(setq vim-empty-lines-excluded-packages
      '(vi-tilde-fringe))

After:

(setq vim-empty-lines-packages
      '(
        (vim-empty-lines-mode :location local)
        (vi-tilde-fringe :excluded t)
        ))

A new file called layers.el is in charge of layers dependency, i.e. when a layer needs to declare additional layers. Previously this was done in the config.el file, to avoid errors you'll have to move the calls to the functions configuration-layer/declare-layer and configuration-layer/declare-layers to a dedicated layers.el file. An example can be found in the spacemacs distribution layer.

The method to install all packages supported by Spacemacs has been improved. The old way was to set the variable dotspacemacs-configuration-layers to the value all. This method had several major drawbacks like forcing all layers to be marked as used and it triggered various bad side effects. We removed the support for the value all.

A new variable dotspacemacs-install-packages is now dedicated to control what packages are downloaded by Spacemacs. Three behaviours are supported:

• used-only (default) will download only the used packages
• used-but-keep-unused will download only the used packages but won't uninstall them if they become unused
• all will download all the supported packages by Spacemacs.

Here is the scary section, the one feared by most users :-) Let be honest, there is a rather big amount of changes for users jumping from master 0.105 to 0.200.

First of all the most visible change is for SPC SPC which triggers now M-x instead of avy to jump to a character. The SPC key in Spacemacs is a central key as it acts as the leader key for all the key bindings, it made sense to give the same sense of "root" key to the sequence SPC SPC, so now SPC SPC is the central sequence to execute any interactive function in Emacs.

Where is the avy command then ? We reorganised from the ground up the prefix SPC j for all jump commands. In the conventions a doubled key is often used for the default command under a given prefix, for instance SPC b b is for buffer selection, SPC f f for file selection etc… The "jump to character" command of avy is then under SPC j j. Here is a detailed list of the new SPC j prefix:

• avy commands are now behind the prefix SPC j for jump:
  • SPC j j to jump to a character in the buffer (works as an evil motion)
  • SPC j l to jump to a line with avy (works as an evil motion)
  • SPC j w to jump to a word in the current buffer (works as an evil motion)
• the following key bindings have been moved:
  • SPC j j to split a line has been moved to SPC j n (mnemonic is New line)
  • SPC j h and SPC j l have been moved to SPC j 0 and SPC j $ respectively.
  • SPC J to split a string or sexp has been moved to SPC j s

A lot of other handy commands are under this prefix, I let you discover them with the which key menus.

Closing, deleting or killing things ? This can be a tough call to distinguish them and we can find such confusion in the Spacemacs key bindings, for instance we close a window but we delete a buffer and we can also kill a buffer. Whereas it can make sense for a lot of users, there are still users finding this confusing. So we decided to simplify the notion of "closing/deleting" things under the d key for delete. We moved SPC w c and SPC w C to SPC w d and SPC w D.

More generally we tried to map prefixes SPC b and SPC w to the same actions and bring a convention with avy commands with the capital letter to manipulate windows and buffers. The result is detailed here:

• SPC b k has been removed.
• SPC b C-k (kill buffer matching regexp) is now SPC b C-d
• SPC b m (buffer move) has been removed because the functionality is available via SPC w with SPC w h/j/k/l, SPC w H/J/K/L and SPC w M.
• SPC b K (kill other buffers) is now SPC b m to map with SPC w m (maximize buffer/window which effectively delete other windows).
• SPC b D now kills a buffer using ace-window.
• Buffer actions don't delete the windows by default, use the universal prefix argument to do so, for instance SPC u SPC b d and SPC u SPC b D will delete the buffer and also the window. Another example is SPC u SPC b m to maximize a buffer.

Helm has a new friend in this release, it is called ivy and it has more and more adopters. Since we have now a new package capable of doing helm commands we decided to remove all helm related command from the prefix SPC h. SPC h is now exclusively for help commands and the following helm commands has been moved:

• SPC h b for =helm-filetered-bookmarks~is now SPC f b
• SPC h l for helm-resume is now SPC r l
• SPC h L for helm-locate-library is now SPC f e l

The git related commands have been drastically simplified to leverage the magit dispatch menu. Instead of replicating all the magit dispatch keys under the SPC g prefix we now only define the key binding SPC g m to display the magit dispatch menu. We get several benefits by doing so: first we free up a lot of valuable keys under SPC g, second we have now more consistent key bindings since we always use the magit dispatch menu. Previously we have some actions bound to different keys between SPC g and the magit dispatch menu accessible under ?. The new available keys allowed us to move some key bindings directly under SPC g like git-link which is now under SPC g l, it makes more sense to have it under SPC g l since it is agnostic of the hosting platform (i.e. it works with GitHub, GitLab etc…).

Spacemacs layouts now restrict the scope of the buffer list opened with SPC b b. Use SPC b B to list all the buffers of all the layouts. Also 1,2,...,9,0 keys now select a layout and close the layout menu, use C-1,C-2,...,C-9,C-0 to switch to a layout and keep the menu opened.

To conclude this section about key binding changes and breaking changes the micro-states in Spacemacs are dead, say hi to the transient-states. We took advantage of the micro-states refactoring to change the name to a more accurate new name transient-states, indeed these states leverage the notion of transient maps in Emacs. The refactoring replaces the custom back-end by hydra a powerful and very popular package to define transient maps. In effect the macro spacemacs|define-micro-state is deprecated and is replaced by the new hydra powered macro spacemacs|define-transient-state.

The layer system has been rewritten to index packages information, the startup time of Spacemacs should be reduced by 20~25%. Also this refactoring will better scale as we add new layers and packages to the distribution.

The spacemacs distribution layer has been split into several layers under the spacemacs directory. Users can now easily customize their Spacemacs experience by choosing the spacemacs-base distribution and using only the spacemacs layers they want.

An exhaustive list of all the spacemacs layers:

• spacemacs-completion
• spacemacs-editing
• spacemacs-editing-visual
• spacemacs-evil
• spacemacs-language
• spacemacs-layouts
• spacemacs-misc
• spacemacs-org
• spacemacs-ui
• spacemacs-ui-visual

For people wanting an even more bare Emacs experience try the distribution layer spacemacs-bootstrap which installs only essential packages like use-package, which-key, etc…

Also it is easier to select or exclude a sub-list of packages in a layer with the new keyword :packages. For instance here is an example to select only the packages fill-column-indicator and golden-ratio in the layer spacemacs-ui-visual:

(setq dotspacemacs-configuration-layers
  (spacemacs-ui-visual :packages fill-column-indicator golden-ratio))

Another example to select all the packages except fancy-battery:

(setq dotspacemacs-configuration-layers
  (spacemacs-ui-visual :packages (not fancy-battery))

This is one of the Achilles' heel of Spacemacs. We rely on bleeding edge version of packages from melpa repository to install a fresh version of Spacemacs. If the repository is down then no sugar, try again later.

With 0.200 we introduce mirrors for all elpa repositories used by Spacemacs. If one of them is down then Spacemacs falls back on the mirror hosted on GitHub. Obviously the fall-back repository should not be used as a primary repository and should only be used when official elpa repositories are down.

It is also possible to freeze packages by adding their name to the new variable dotspacemacs-frozen-packages. Frozen packages cannot be updated or rollbacked. This is useful if a package upstream needs a fix, the package can be frozen until the fix is released.

Packages can be stored in different elpa directories, the most useful setting is maybe to define a different directory per Emacs version. You can do it by setting the new variable dotspacemacs-elpa-subdirectory to the value emacs-version. By default the value of this variable is nil which means that all packages are installed in the same elpa directory.

A feature borrowed to Prelude distribution and adapted to the layers, it allows to install a layer and all its packages when opening a new file with a supported extension.

For instance, when opening an Elixir file with extension .ex Spacemacs will ask to install the elixir layer if it is not already used. The elixir layer is automatically added to the dotfile so it won't be uninstalled after a restart.

By default this feature is disabled, you have to opt-in for it by setting the variable dotspacemacs-enable-lazy-installation to one of the following values:

• unused to lazy install only layers not listed in dotspacemacs-configuration-layers
• all to lazy install any layer supporting lazy installation (i.e. even the used layers won't be installed at startup until you open a file with a supported extension).

The Hybrid state wanders between the Emacs style and the Evil style, three new variables allow to fine tune the Hybrid style experience:

• hybrid-mode-enable-evilified-state, if non nil then buffers are evilified,
• hybrid-mode-enable-hjkl-bindings, if non nil navigation on hjkl keys is enabled (for instance in helm or ivy buffers),
• hybrid-mode-default-state, the default state when opening a new buffer, by default it is normal.

To define these new variables use the :variables keyword. For example:

(setq dotspacemacs-editing-style '(hybrid :variables
                                   hybrid-mode-enable-evilified-state t
                                   hybrid-mode-enable-hjkl-bindings t
                                   hybrid-mode-default-state 'normal))

The community has made a wonderful work to bring ivy support to Spacemacs.

Want to switch from helm to ivy? This is as simple as adding the ivy layer to your dotfile and reloading it with SPC f e R!

The level of feature of the ivy layer is pretty on par with the helm layer, this is a fantastic work and it demonstrates all the power of a community-driven configuration. I'm really excited by this new feature and how it is so easy to enjoy it. Nice work guys!

Transient-states replace the micro-states. They are powered by hydra making hydra part of the bootstrap packages (pillars of the distribution). Hydra is now 100% supported in Spacemacs and does not require hacks to work correctly.

We tried to get consistent transient-states in all the layers by keeping the same documentation strings format everywhere.

Emacs comes with lots of tools to help the user to debug their configuration. Spacemacs adds several concepts which can make harder for a user to debug his configuration, especially the layer system.

In this new release we are eager to introduce new easy way to debug your configuration:

• press SPC q d to restart Emacs in debug mode with command line parameter --debug-init fed in for you
• press SPC q D to restart Emacs with a selected list of packages to load, in this mode Spacemacs is completely disabled so you get the perfect way to test whether a bug comes from Spacemacs configuration or not
• press SPC h I to open an org buffer with an issue template, fill it then press C-c C-c to submit it with your default internet browser.

Along with these new key bindings, new Spacemacs specific command line parameters are available to help you change the scope of an issue investigation:

• --no-layer deactivates all the layers except the distribution layer
• --distribution x allows to change temporarily the distribution to x.

This is a good time to remind you about the other useful Spacemacs specific command line parameters:

• --profile= will display profiling information on startup
• --timed-requires will display the time taken by each require commands
• --adv-timers n will display any load time greater than n.

A new layer keyboard-layout aims to provide the tools to define more easily new keyboard layouts. This release ships with support for bépo and dvorak layouts.

Be sure to follow the README.org of the keyboard-layout layer for more information about layout definition.

Per-directory and file local variables are a standard feature of Emacs, we try to leverage them starting with 0.200. Some layers support several tools to do the same thing, for instance in the ruby layer both rspec and ruby-test are supported to run tests; the haskell layer supports several completion back-ends like intero and ghci. Those tools or back-ends are project specific so providing only a global value for them is not enough. With 0.200 these layers become compatible with directory local variables so the test engine for ruby or the completion back-end for haskell can be setup differently for different directories (i.e. projects).

Supporting directory and file local variable dynamically greatly improves the flexibility of Spacemacs and make it an even better choice to handle various types of projects. We don´t support multiple options for the sake of supporting them but for a more robust solution capable to deal easily with your day-to-day requirements.

We have even more abstraction of useful concepts in 0.200 like jumping to the definition of a symbol or opening a REPL.

Like text searching tools, there is now the concept of jump handlers, each mode can set a list of jump handlers and Spacemacs will try them in order to get you to a symbol definition. This new abstraction alows to merge the different jumping tools under the same key binding, for instance dumb-jump, tags etc…

All supported REPLs are now registered in a list and you can run any registered REPL with SPC a '.

The contents of the welcome screen are now centered, there is also a nice new footer. The contents are recentered when the window is resized, to disable this behaviour set the variable dotspacemacs-startup-buffer-responsive to nil.

Sizes of lists in the welcome screen can be customized independently for each list with the variable dotspacemacs-startup-list, for instance the following value will display a maximum of 5 items for the recent files list and a maximum of 7 items for the projects list:

(setq dotspacemacs-startup-lists '((recents  . 5)
                                   (projects . 7)))

There are two new lists of items which can be displayed on the welcome screen:

• agenda
• todos

In previous versions Spacemacs checked for a new version at every startup of Emacs and every 6 hours. It was stressing the GitHub infrastructure enough to make GitHub throttle down the traffic for the repository.

In this version we changed the notification frequency and took several measures to reduce the git commands monitored by GitHub:

• reduce number of required git commands per check from 3 to 1
• remove recurrent version check every 6 hours, i.e. the check happens only at startup
• rate limit the checks to once per day
• change default value of variable dotspacemacs-check-for-update to nil
• make function spacemacs/check-for-new-version interactive so checking for a new version can be done on demand.

If you want automatic check of new version you have now to opt-in by setting dotspacemacs-check-for-update to t.

At the root of the project directory the new file COMMUNITY.org describes the values of the project and the moderation rules. There is also an exhaustive list of the moderation actions taken by collaborators.

You can now show your support for Spacemacs by buying tee-shirts and goodies in the new Spacemacs shop!

There is a limited number of models for women but all the men tee-shirts will be available for women as well in the coming weeks!

Elpa mirrors are a good start but it does not fix the bleeding edge packages issue, especially when installing a fresh version of Spacemacs.

For 0.201 we plan to introduce stable snapshots of elpa repositories, a new installation of Spacemacs will always install packages from this stable source. Users will then be able to manually trigger an upgrade of packages if they want the bleeding edge versions but they will always be able to rollback to the previous stable state if required.

One of the main focus for 0.201 will be to integrate emacs-purpose. It is a package to display buffer in the same windows. The current pull request is very popular and I'm sure you'll like what it will bring to the Spacemacs experience.

Pull requests with new layers are low on the priority list because reviewing them is more time consuming. For 0.201 I'll focus on all the pull requests with new layers in order to speed up the merge so you can expect more new layers for 0.201 than 0.200.