#+TITLE: Newsletter #01: About the 0.200 release

* Newsletter #01: About the 0.200 release                 :TOC_4_gh:noexport:
 - [[#introduction][Introduction]]
 - [[#breaking-changes][Breaking changes]]
   - [[#support-for-emacs-243-has-been-dropped][Support for Emacs 24.3 has been dropped]]
   - [[#some-modifications-in-the-layer-format][Some modifications in the layer format]]
   - [[#controlling-downloaded-packages][Controlling downloaded packages]]
   - [[#key-bindings][Key bindings]]
 - [[#whats-new-][What's new ?]]
   - [[#startup-improvments][Startup improvments]]
   - [[#improved-composability][Improved composability]]
   - [[#improved-stability][Improved stability]]
   - [[#lazy-installation-of-layers][Lazy installation of layers]]
   - [[#a-better-hybrid-editing-style][A better hybrid editing style]]
   - [[#support-for-ivy][Support for Ivy]]
   - [[#better-transient-states][Better transient-states]]
   - [[#more-debugging-tools][More debugging tools]]
   - [[#new-keyboard-layouts][New keyboard layouts]]
   - [[#directory-and-file-local-variables][Directory and file local variables]]
   - [[#more-useful-abstraction][More useful abstraction]]
   - [[#new-welcome-screen][New welcome screen]]
   - [[#about-spacemacs-update-notifications][About Spacemacs update notifications]]
   - [[#a-new-community-document][A new community document]]
   - [[#the-spacemacs-shop][The Spacemacs shop]]
 - [[#whats-next-][What's next ?]]
   - [[#even-more-stability][Even more stability]]
   - [[#more-consistent-window-behaviour][More consistent window behaviour]]
   - [[#new-layers][New layers]]
 - [[#a-few-thanks][A few thanks]]

* Introduction
0.200 is a huge release with more than 1700 commits since the last major version
released in January 2016. Actually it is so big that we jumped directly from
version 0.105 to version 0.200, so don't panic if you think you missed all the
versions since 0.105 :-)

This first newsletter describes with details the main changes introduced in the
new version and gives some explanation about the various choices made during the
last months.

The (boring) complete list of changes can be found in the file =CHANGELOG.org=
at the root of the Git repository.

Let's start with the hottest section: breaking changes!

* Breaking changes
Before starting with the breaking changes let me begin with a few words about
the motivation behind those changes. Spacemacs moves at an incredible pace
thanks to a big and active community, the project already counts more than 400
contributors! With such a high number of contributors lots of new ideas are
proposed to constantly evolve and improve the project, some of them make a lot
of sense and we give them priority over backward compatibility, this is
especially true with key bindings. In this release quite a few changes have been
made to the key bindings, some of them are deep changes and anyone using the
develop branch had to adapt to them at some point, the result seems to worth it.

** Support for Emacs 24.3 has been dropped
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 [[https://gitter.im/syl20bnr/spacemacs][Gitter chat]], I'm sure you'll find solutions there.

** Some modifications in the layer format
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:_

#+BEGIN_SRC emacs-lisp
;; in extensions.el
(setq python-post-extensions
  '(
    nose
    pylookup
    python-compile
    py-yapf
    ))
#+END_SRC

_After:_

#+BEGIN_SRC emacs-lisp
;; in packages.el
(setq python-packages
  '(
    ;; skipping packages before...
    (nose :location local)
    (pylookup :location local)
    ;; skipping packages after...
    ))
#+END_SRC

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

_Before:_

#+BEGIN_SRC emacs-lisp
(setq vim-empty-lines-packages
      '(
        (vim-empty-lines-mode :location local)
        ))

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

_After:_

#+BEGIN_SRC  emacs-lisp
(setq vim-empty-lines-packages
      '(
        (vim-empty-lines-mode :location local)
        (vi-tilde-fringe :excluded t)
        ))
#+END_SRC

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
[[https://github.com/syl20bnr/spacemacs/blob/564cbc40eda936985325c9b79088fbcb39d9a69d/layers/%2Bdistributions/spacemacs/layers.el][spacemacs distribution layer]].

** Controlling downloaded packages
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.

** Key bindings
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=.

* What's new ?
** Startup improvments
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.

** Improved composability
The =spacemacs= distribution layer has been split into several layers under
the =spacemacs= directory. The user can now very easily customize her Spacemacs
experience by choosing the =spacemacs-base= distribution and using only the
=spacemacs= layers she wants.

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

#+BEGIN_SRC  emacs-lisp
(setq dotspacemacs-configuration-layers
  (spacemacs-ui-visual :packages fill-column-indicator golden-ratio))
#+END_SRC

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

#+BEGIN_SRC  emacs-lisp
(setq dotspacemacs-configuration-layers
  (spacemacs-ui-visual :packages (not fancy-battery))
#+END_SRC

** Improved stability
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 [[https://github.com/syl20bnr/spacemacs-elpa-mirror][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.

** Lazy installation of layers
A feature borrowed to [[https://github.com/bbatsov/prelude][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).

** A better hybrid editing style
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:

#+BEGIN_SRC emacs-lisp
(setq dotspacemacs-editing-style '(hybrid :variables
                                   hybrid-mode-enable-evilified-state t
                                   hybrid-mode-enable-hjkl-bindings t
                                   hybrid-mode-default-state 'normal))
#+END_SRC

** Support for Ivy
The community has made a wonderful work to bring [[https://github.com/abo-abo/swiper][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!

** Better transient-states
=Transient-states= replace the =micro-states=. They are powered by [[https://github.com/abo-abo/hydra][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.

** More debugging tools
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 wether 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=.

** New keyboard layouts
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.

** Directory and file local variables
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html][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.

** More useful abstraction
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 '~.

** New welcome screen
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:

#+BEGIN_SRC emacs-lisp
(setq dotspacemacs-startup-lists '((recents  . 5)
                                   (projects . 7)))
#+END_SRC

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

** About Spacemacs update notifications
In previous versions Spacemacs checked for a new version at every startup of
Emacs and every 6 hours. It was [[https://github.com/syl20bnr/spacemacs/issues/6692][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=.

** A new community document
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.

** The Spacemacs shop
You can now show your support for Spacemacs by buying tee-shirts and goodies
in the new [[https://shop.spreadshirt.com/spacemacs-shop][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!

* What's next ?
** Even more stability
=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.

** More consistent window behaviour
One of the main focus for 0.201 will be to integrate [[https://github.com/bmag/emacs-purpose][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.

** New layers
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.

* A few thanks
This first newsletter is a great opportunity to thanks the Emacs community and
more specifically:

- =Justin Burkett= (aka [[https://github.com/justbur][justbur]]) and =Fabien Dubosson= (aka [[https://github.com/StreakyCobra][StreakyCobra]])
  who were collaborators during several months. This version would not be so
  awesome without their dedicated involvement. We wish them all the success in
  their future projects.

- =Boris= (aka [[https://github.com/d12frosted][d12frosted]]) who joined =TheBB= and myself as collaborator.

- Of course the unique =Eivind Fonn= (aka [[https://github.com/TheBB][TheBB]]) without his constant support
  Spacemacs could not be successful and I think I would have burn-out a long
  time ago.

- All the package maintainers, especially =Oleh Krehel= (aka [[https://github.com/abo-abo][abo-abo]]) for the
  great help with =ivy= and obviously =Frank Fischer= (aka [[https://bitbucket.org/lyro/][lyro]]) the author
  of =evil=.

- In no specific order: =Diego Berrocal= (aka [[https://github.com/CestDiego][CestDiego]]), [[https://github.com/bmag][bmag]], [[https://github.com/NJBS][NJBS]],
  =Eugene Yaremenko= (aka [[https://github.com/JAremko][JAremko]]), [[https://github.com/travisbhartwell][Travis B. Hartwell]], =Tristan Hume=
  (aka [[https://github.com/trishume][trishume]])

- All the Spacemacs community, you are the heart of Spacemacs!