Creating an Open Source JavaScript Library on Github

Semantic Versioning with NPM

Kent C. Dodds

Kent C. Dodds

Professional Trainer
Creating an Open Source JavaScript Library on Github

Check out a free preview of the full Creating an Open Source JavaScript Library on Github course

The "Semantic Versioning with NPM" Lesson is part of the full, Creating an Open Source JavaScript Library on Github course featured in this preview video. Here's what you'd learn in this lesson:

Before adding automation with the semantic-release Node module, Kent manually versions the library from the command line with NPM. He bumps the version with the “npm major” command and then demonstrates a few other features like patching and deprecating.

Preview
Close

Transcript from the "Semantic Versioning with NPM" Lesson

[00:00:00]
>> [MUSIC]

[00:00:03]
>> Kent C. Dodds: I'm gonna show you how to do this probably normally if you were on a meaning stuff. The most common way to bump your version is to use npm. And npm, actually I just show you the docs page, docs.npmjs.com, publish.
>> Kent C. Dodds: Version, nope, here let's go, version.
>> Kent C. Dodds: Version, where did it go?

[00:00:35]
Well there's, okay, we'll go ahead and just do this, npm version --help.
>> Kent C. Dodds: So this allows you to specify what type of version you want it to be. And so we're gonna say npm version major cuz we're gonna publish a major release. And yeah, so we'll just say npm version major.

[00:01:03]
It's gonna do a couple of things. First, it's gonna update our package.json, and then it's going to also update our tags. How do I find what tags there are? Git list tags.
>> Kent C. Dodds: Let's do git tag. So npm is responsible for adding that tag to our most recent commit.

[00:01:26]
So a tag is just like a thing that points to a commit, that's all that it is. But GitHub uses tags to have that release its page. And so it points to a commit and then you can download the source code from that commit and all the interesting things.

[00:01:42]
We pretty much are only gonna use for the change line. So yeah, once you have run npn version major, then you can run npn publish, again, and you're publishing a major version. If you want to you can like, [LAUGH] you know what's hilarious is I totally didn't rerun my build after I deleted the dist directory.

[00:02:05]
So I just published a major version that has nothing in it. This is why we automate releases. So if I go to github-names, I've got that 2.0 release. But if I view the code, we've got nothing in here. [LAUGH] So we're gonna do a bug fix real quick before anybody notices.

[00:02:28]
So we'll do npm version patch, and then we'll get npm publish
>> Kent C. Dodds: And then I'll show you how to deprecate a package. We kind of already saw that, but I'll actually do it this time. Deprecate, we're going to just make sure I know what the command is. Okay, yeah, npm deprecate, package is, github-names@2.0.0.

[00:03:04]
And then the message is gonna be, whoops, yeah. That was not a helpful message at all, please don't do that. [LAUGH] But yeah, so that's whole bunch of stuff about npm and. Did I already publish, you know what's funny, I forgot to run the build again. [LAUGH] This is so embarrassing.

[00:03:31]
Okay, now npm version, or yeah, patch again, and npm publish, and I'm not gonna worry about deprecating that other one. You all know how to do that, so we're gonna continue on. But with all those words about npm, I'm gonna go ahead and stop and give everybody a opportunity to ask any questions that you have.

[00:03:57]
Was everybody able to publish a new major version of the package? Okay, we've got some 2.0s? Raise your hand online if you got that. Ivan is asking, so the way to solve it is to wait and hold to more changes? Ivan, if you don't want to publish readme changes and stuff like that, yeah, that's the way.

[00:04:20]
But here in a second I'm gonna talk about our love for version numbers and why it's kind of silly. So any other questions?
>> Kent C. Dodds: Okay, cool. So let's talk about our love for version numbers. There's something in us that just says, when I go from two to three, that's a big deal and this is something to market and it's exciting.

[00:04:45]
And Angular hasn't even released version two yet, can I possibly release a version three? How audacious of me. I have libraries that are up to eight, I don't think I've ever gotten a library up to nine before. It really, just let go of that love for big marketing releases and big, this is breaking changes, breaking the world.

[00:05:10]
And so we're gonna save all these up, whatever. As far as breaking changes are concerned, that's okay. If you want to, there's there's something to be said about managing a community and not breaking the community all the time. But we have sumver for a reason. And so the difference between 2.0.0 and 2.0.1, that's really not a big deal.

[00:05:34]
So if it's just a docs change, yeah sure, go ahead and publish your release, not a big deal. And pushing a breaking change shouldn't matter quite as much, especially if it's a really small breaking change. Just bump the major version number, communicate to the community, hey, you just need to swap these two arguments because that was a bad API in the first place or something.

[00:05:58]
And now it enables us to do this special currying thing or whatever. Then yeah, just publish a major change, it's okay. If people, as long as people aren't doing things that they shouldn't, like using the star in their version ranges, then you're not, you shouldn't be breaking people by doing that.

[00:06:20]
So yeah, don't worry about it. Just publish, publish all the time. Any changes about that? Sweet. Numbers are for computers. Yeah, you do need to manage your community, and if it's a big project and stuff, manage your major versions. But for the most part, just publish.

Learn Straight from the Experts Who Shape the Modern Web

  • In-depth Courses
  • Industry Leading Experts
  • Learning Paths
  • Live Interactive Workshops
Get Unlimited Access Now