diff --git a/core/core-documentation.el b/core/core-documentation.el index 9d3a7b12c..35b00e8bc 100644 --- a/core/core-documentation.el +++ b/core/core-documentation.el @@ -202,10 +202,18 @@ preprocessors for the exported .org files." (org-html-htmlize-output-type 'css) (org-publish-project-alist `(("spacemacs" - :components ("spacemacs-doc" + :components ("spacemacs-news" + "spacemacs-doc" "spacemacs-doc-static" "layers-doc" "layers-doc-static")) + ("spacemacs-news" + :base-directory ,spacemacs-news-directory + :base-extension "org" + :publishing-directory ,(concat publish-target "news/") + :publishing-function org-html-publish-to-html + :headline-levels 4 + :html-head ,header) ("spacemacs-doc" :base-directory ,spacemacs-docs-directory :base-extension "org" diff --git a/core/core-load-paths.el b/core/core-load-paths.el index e09ceb7c2..0c752b3be 100644 --- a/core/core-load-paths.el +++ b/core/core-load-paths.el @@ -50,6 +50,9 @@ (defconst spacemacs-docs-directory (expand-file-name (concat spacemacs-start-directory "doc/")) "Spacemacs documentation directory.") +(defconst spacemacs-news-directory + (expand-file-name (concat spacemacs-start-directory "news/")) + "Spacemacs News directory.") (defconst spacemacs-assets-directory (expand-file-name (concat spacemacs-start-directory "assets/")) "Spacemacs assets directory.") diff --git a/news/news01.org b/news/news01.org new file mode 100644 index 000000000..1a84ce0e1 --- /dev/null +++ b/news/news01.org @@ -0,0 +1,435 @@ +#+TITLE: Newsletter #01: About the 0.200 release + +* Newsletter #01: About the 0.200 release :TOC_4_gh:noexport: + - [[#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]] + - [[#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]] + - [[#a-few-thanks][A few thanks]] + +* 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! As such a lot 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 a lot of changes has been done to the key bindings, a few of them are +deep changes and anyone using the develop branch had to adapt themselves to +these changes at some point, be it users, contributors or collaborators so you +are not alone. + +** 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 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 =-excluded-packages= are now ignored, they have been +replaced by the =:excluded= keyword in =-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 move 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 the more +accurate new name =transient-states=, indeed thoses 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... + +** 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. + +** 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 dofile 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). + +** 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= allows to change temporarily the distribution + +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. The =0.200= 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 variable 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 is now centered with a new footer. + +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 + +** 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. + +** 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. + +If you want automatic check of new version you have now to opt-in by setting +=dotspacemacs-check-for-update= to =t=. + +** 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]]! + +* 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 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 =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. + +* 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.