Syntax-themes & packag.json: How can I tell which atom version to set under "engines"?

Syntax themes list the atom version in their package.json, presumably because higher versions supply additional (or deprecate old) selectors to target.

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

My question is, where can I find out which range to set for my theme? I noticed that some themes have a lower bound starting below or above 1.0.0 for instance.

I wish the flight manual covered syntax-themes in more detail, e.g. which files and settings are required/fixed and which are up to the author.

@adrian5:
The version number range you refer to in your topic, refers to all sub versions in major version 1. The ideal is that the API remains more-or-less stable within a major version. Refinement can be expected. The ideal situation is not always achievable.

The API documentation (https://flight-manual.atom.io/api/v1.41.0/AtomEnvironment/) has a version selection that can roll back in version numbers. Whichever API you use can be checked against those if you wish.

I would guess that the theme structure would be very stable.
A quick check reveals a version β€œ>0.50.0” or β€œ>0.40.0”
a) https://github.com/atom/atom/blob/master/packages/one-dark-syntax/package.json#L14
b) https://github.com/atom/atom/blob/master/packages/one-light-ui/package.json#L15

How about using something like β€œ>1.20.0”?
Anything lower should not carry a concern, in my opinion.

1 Like

The Atom developers, like most Node developers, use Semantic Version. Following its standards means that breaking changes will only be introduced in major releases (e.g. from 1.x to 2.x). Nobody knows if packages/themes will work differently in Atom 2.x, so specifying a version range between 1.x and 2.x is a way of playing it safely.

At this point it’s probably more common to adjust the lower version, for instance if the package/theme requires functionality that was introduced after Atom 1.0.0. One practical example would be if a package provides a grammar for the new tree-sitter parser, it should target Atom 1.25 as minimum version. As for themes, another practical example would be Atom 1.13 and its Shadow DOM removal.

1 Like

That makes sense, thank you both!