Problems every time I update Atom


This is a problem that had been hauting me since the Atom 1.0 release. Seems like the API is changing way faster than pre-release…

The main problem is that Atom’s changelog is FAR FROM COMPLETE. I’m putting this in all caps, and in bold, because this have been a real challenge for me, as I’m writing lots of packages but most of the time I’m just correcting bugs that have hapened from one version to another…

First of all, there’s the “we never told you it would work that way” excuse, like in my ticket:

In this new version, I’ve discovered that returns a Javascript promise, one that have no method promiseDispatch, like it was in the past. But there’s no place in changelog when this was informed… and no deprecation warning when I’m doing incremental updates. And all this in less than three months!

It’s becoming quite complicated to mantain packages this way… does someone is having the same problem? How are people dealing with this? Even worse, everytime I update some strange thing breaks in misterious ways! In the current version I’m using (1.2.4), the focus is broke when I’m triggering “file finder” (CTRL+P shorcut). Other than that, packages like Vim-mode change the name of namespaces, or change the way keystrokes work, to the point that I have uninstalled the official version and installed “vim-mode-plus”…

What’s happening with Atom?


Have you seen the latest change log information on the page? Is this more what you’re looking for?


That’s precisely the place I’m looking for.

So far, the problems:

  1. No information that providers and consumers are asynchronous
  2. No information that no longer supports promiseDispatch
  3. No information about API changes

Furthermore, the problems in deprecation cop that simply doesn’t inform me of changes in my packages.


I understand you’re frustrated. I would be too if I thought I was constantly trying to make progress on a shifting landscape.

I think we agree that Atom, as a product, must improve. This means that changes have to be made to Atom’s code base. You are correct that we could communicate some things better. The Atom team agrees! That is why the change log information on the Releases page has become significantly more detailed. From this:

To this:

(And that’s not even close to half of the information that was included this time.)

There is also the Atom blog where changes are often discussed in greater detail:

I disagree though that there has been no information about API changes. You can find information in releases about marker layer improvements, information on test runner changes, and information on things that were accidentally broken.

If you have specific suggestions on how to improve, perhaps some guidelines that would help the Atom team choose better what to include in the change log … that would be a great help!


Ok, I’m gonna explain in detail my problems.

First of all, I use Linux. In Linux, atom doesn’t auto-update, so I cannot guarantee that I’ll jump from 1.1.0 to 1.1.1. So, most of the time, I’m jumping like 2 minor versions.

Two: <-- this says that Atom uses Semantic Versioning beginning on 1.0 version. When I use Package Generator, it even adds the following information in my package.json:

"engines": {
  "atom": ">=1.0.0 <2.0.0"

So, even package generator is expecting that Atom uses Semantic Versioning, and expecting no API changes till the 2.0 version. It is not. This is the case - I’m seeing a lot of api changes on 1.0, to 1.1, to 1.2. This includes:

  • Simple thing that seems to be “forgotten”, like atom.workspace.getActiveEditor (it should be getActiveTextEditor, the old version was removed in some post 1.0 version)
  • Things that are poorly documented and then changed (like, that simply says: Returns a promise that resolves to the TextEditor for the file URI, but in a previous version it was not a Javascript Promise, so I couldn’t use .then - I was stuck with .promiseDispatch, and needed to get the value using valueOf).
  • Things that were not asynchronous, and began to be, breaking packages in strange ways.

Two of these things should be easy to solve (the last one, not so easy) - for instance, let’s see the case for - it should return, somewhere in code:

promise = callOpenFileProcess()

promise.valueOf = ->
promise.then (value) -> 
  # code to make DeprecationCop warn that this is deprecated
  promise.valueOf = -> value
promise.promiseDispatch = (fn) ->
  # Code to make DeprecationCop warn that this is deprecated
  promise.then -> fn()

Ok, I know this code is awkward. But this is the price of Semantic Versioning - it is not an easy task. The code above would need no changes in Changelog (except when making things that were synchronous to assynchronous, or other changes that are not reflected in the API but can cause package breaks), because DeprecationCop would warn me nice and clear when there’s something wrong with my package. When using the post 1.0 version of Atom, I have a feeling that I have a powerful weapon (deprecation cop) that was very useful in the past (pre-1.0 releases) but now it’s useless…

Furthermore, I would suggest is that Atom makes a pre-2.0 version - a beta release cycle where the API changes, in favor of better performance or better code. It would be the user’s choice to use it, and when using it, the user would expect some package breakage, in favor of a faster (and possibly more stable) editor. For the rest of users, we’ll use the oficial non-beta releases, where there’ll be no changes in APIs.

Now, the problems in the approach you show me:

  1. Like I said, everytime I update Atom, I update 2 minor versions. This means that if I’m going to check if there are API changes, I must go to the changelog file, check there. Then, check on each release page to see if there’s some API change that I remember using in one of my 5-6 packages. Then, I’ll go to the Atom Blog, and check there. Then, check changes in Electron API.
  2. Just for the record, I’ve checked on the releases page. In a simple search for promise and .open, I found no information that has changed the kind of promise it returns. So, this would not help me.
  3. I know this may sound rude, but I don’t make money for package creation. I’m using Atom right now, in place of a faster editor (like Sublime Text) or a console-and-gui one (like Vim, neoVim, or Emacs) because it’s the best editor to create plugins. And, everytime I create a plugin, I spend time on it, and sometimes I could use this time to work on other projects. So, this is more than simply frustrating - it’s time and money-consuming, and it’s becoming unsustainable.

I hope the Atom team understands these concerns. As I told, it’s a great editor for writing packages - but, if mantaining these packages becomes too dificult, or if to update Atom I should check three or four diferent places to check if nothing will break, it’ll lose most of its power.


Semver allows API changes between major versions. It requires that any changes between major versions are backwards compatible. So if you’re expecting zero API changes until 2.0, then I believe that is unrealistic and against the tenets of Semver as documented.

You keep mentioning this example. And I have to disagree with you that this was an unreasonable change. All that was documented was that would return a Promise. This wasn’t “poorly documented”, it was a conscious choice. The Atom team didn’t want to use the Q library forever. They wanted to use native JavaScript promises once the engine got to the point where they could. So they only promised what they intended to deliver … that the API would return some kind of Promise.

You were depending on an undocumented implementation detail. This is always a bad idea. It doesn’t matter if you’re working with an open source project or a huge monolithic piece of software that changes at a glacial pace. If all that is promised is X but you decide on your own that what that means is X+Y+Z, then eventually you’re going to run into problems. And your other example is much the same … you assumed things that were never promised and then expect the Atom team to hold fast to something that was never agreed to.

Semver was created to make explicit the ways that a software project won’t change … but also how it is allowed to change.

The Atom team does understand these concerns. And they are doing their best to deliver a great product while holding fast to the API that they promised as documented. I agree that sometimes mistakes are made and the Atom team is trying to get better at controlling that.

I’ll suggest that there be a special section in the CHANGELOG for API changes so that in the future you have one place to look for these kinds of things.


But that’s exactly the problem! There’s only a way to interact with promises - resolve then. And this very code has changed! And changed without any deprecation warning from Deprecation Cop or anything.

The problem is that what I’m seeing here is kind of unrealistic. So, Atom team documents it would deliver some kind of promise. How do you suggest I should program my code with this information? In your own words, I cannot depend on undocumented implementation detail. The return kind of promise, and methods to resolve it, were “details”? How can I work around this case, or others that returns promises?


I’ve opened this Issue to clarify the documentation around Promises in the Atom API to hopefully prevent future misunderstandings:

And I’ve opened this Issue to propose adding an API changes section to future change logs: