API eagerly trims tag names specified to create new package versions

[ghost]

Hello there,

I was directed here (instead of atom/apm) by @lee-dohm on the Atom Slack to report a possible bug in the Atom API.

Historically, I've been able to successfully publish Atom packages on apm using tags of the form x.y.z (i.e. semver, noting the absence of a v prefix). I would use the command apm publish -t x.y.z to accomplish this. However, it seems like something has recently changed with the API to stops me from being able to publish like this any more. A sample error message I get from apm due to a failed publish attempt looks like this:

Creating new version failed: You specified a tag with the version number '.3.1', but the version number in package.json is '0.3.1'. The version numbers must agree before you can publish.

Now, I suspect the API is eagerly trimming the first character of the tag name supplied for publishing. I guess this might be because it's some accepted convention for people tag their versions in the format of vx.y.z (e.g. v1.2.3, not 1.2.3).

After trying to create a new tag that uses a v prefix and publishing that instead (i.e. following on from the above sample error message, I tried apm publish -t v0.3.1), it seems apm happily accepted that tag and published the package.

So, I guess that leaves me wondering whether or not it's now a requirement for Atom packages to publish using v prefixed (or even non-semver) tags, or if the API could be looked at to see whether or not this convenience trimming can be fixed up to be more accommodating.

[50Wliu]

/cc @jasonrudolph

[jasonrudolph]

A sample error message I get from apm due to a failed publish attempt looks like this:

Creating new version failed: You specified a tag with the version number '.3.1', but the version number in package.json is '0.3.1'. The version numbers must agree before you can publish.

...

So, I guess that leaves me wondering whether or not it's now a requirement for Atom packages to publish using v prefixed (or even non-semver) tags ...

@miqid: Yes. Last month, we began enforcing the convention that the version number in package.json must agree with the version number in the Git tag, and the Git tag must use v as the prefix for the version number. In the example above, you can satisfy this convention by using v0.3.1 as the tag name.

---

In case it helps, I'll try to provide some background on last month's change:

In general, we recommend using apm publish [major|minor|patch], as those commands will automatically ensure that your package follows the convention described above. As you may know, when you use apm publish [major|minor|patch], apm increments the current version in package.json and creates the tag. For example, if the current version is 0.3.0 in your package.json file, running apm publish patch will set the version to 0.3.1 in package.json, commit that change to your repository, and tag that commit using v0.3.1 as the tag name.

We realize that some developers prefer to use the lower-level apm publish -t <tag> command (instead of apm publish [major|minor|patch]). Using apm publish -t <tag> requires that you use some other mechanism to increment the version in package.json, commit that change, and create the tag. We want to continue to provide that flexibility, but we also want to avoid confusing and misleading version/tag combinations. For example, prior to this change, it was possible to use apm publish -t <tag> to publish version 1.0.0 of a package where the Git tag is v0.1.2. :see_no_evil: For consistency within the package ecosystem and to minimize confusion, we'd like the resulting version numbers and tags to agree with each other.

With that in mind, we reviewed the packages published in the last 30 days and observed that 99.87 packages already followed the convention that the version number in package.json agrees with the version number in the Git tag, and the Git tag uses v as the prefix for the version number. Knowing that, we chose to began enforcing this convention for newly-published package versions.

That said, I'm sorry for the friction that this change introduced to your previous workflow. I hope the explanation above is helpful. I'm going to close this issue, but if you have any additional questions regarding this change, please let me know.

[ghost]

@jasonrudolph, not a problem and thank you very much for providing a thorough explanation.

As an aside, despite the recommended apm publish x.y.z command to publish an Atom package, perhaps the documentation for apm help publish should be updated to indicate that explicit use of the -t or --tag flag expects the tag name to be of the format vx.y.z (in case somebody isn't aware of this convention).

Thanks again!

[50Wliu]

Now that's an issue that should be filed on atom/apm :wink:.