Bower, NPM, semantic versioning?? Sounds strange? Check out my article Node, Grunt, Bower and Yeoman – A Modern web dev’s Toolkit<\/a>.<\/p><\/blockquote>\n I love to contribute to Open Source libraries on GitHub<\/a> and so should you!. You learn a lot, it’s coding as a hobby (not for being payed) and finally it’s also rewarding, especially when you then see people use your stuff, discuss with them etc. Most of the projects that get shared on GitHub are utility libraries that are designed to be highly reusable across projects. As such (for being discovered and used), they should follow a series of good practices like<\/p>\n The last points are the ones I’d like to address with this article as they’re something I see devs and library publishers often struggle with.<\/p>\n You certainly already have your build scripts in place. Like a Grunt, Gulp, Webpack script or whatever of the currently fancy build tools you’re using. When you have that (and you definitely should), then you’re only steps away from a full blown automated build. Such a continuous integration server is extremely valuable as it builds your code, maybe lints it, executes your tests, frankly, it helps you keep your code working. This becomes even more important when other developers start to contribute to your library (which is the goal after all).<\/p>\n As we will see, it’s super easy to setup such a CI server and it’s even totally free.<\/p>\n I’m mainly talking about JavaScript here as it is currently the prevalent language on GitHub, but it can be easily generalised to other languages as well. When you develop a library and you share it on GitHub, you want it to be used by others. Thus, installing your lib has to be as easy and straightforward as possible. This can be achieved by deploying your lib’s distribution files to so-called package managers. Currently the most used ones are NPM<\/a> and Bower<\/a>. There are other package managers on the way like JSPM<\/a> as well. Deployment is done similarly as with Bower, though.<\/p>\n With distribution or “dist” files I intend the compiled, minified and packaged version of library that will be included in other projects.<\/p><\/blockquote>\n When you release a new version of your library, it is important to communicate your changes. Did you add new features? Just patched some bugs? Are changes breaking? These are important things for a developer in order to know whether it is safe to upgrade. Package managers like Bower and NPM provide even mechanisms to perform automatic upgrades to the next “safe” version. Obviously this only works if you properly follow the semver spec<\/a>.<\/p>\n Sadly, that’s where most libs fail. Should we increment the patch? The minor? Well, we did add some features, but hey…they aren’t thaaat huge.. maybe we should just increase the patch. It doesn’t have to be like that, though. The semver spec is quite clear and should not leave any doubts: machines can do it for us! That’s probably what Stephan B\u00f6nnemann<\/a> thought as well and started to automate the whole stuff. We’ll shortly see how.<\/p>\n Finally, the change log. 95% of the time absent, 5% of the time hand written and often very flaky. It’s like everyone wants to have one, but it’s hard work to get it right.<\/p>\n As someone recently said to me: “work smart, not hard” tl;dr:<\/strong> It’s basically a convention to write your commit messages in a structured way such that can then be easily parsed by a program into a change log. Like..<\/p>\n –<\/p>\n for housekeeping stuff<\/li>\n –<\/p>\n when fixing a bug<\/li>\n –<\/p>\n when adding a new feature<\/li>\n Examples:<\/p>\n or a breaking change<\/p>\n Takes a bit of time to get accustomed, but once you have it, you get nicely readable commit messages.<\/p>\n You know about how to polish your git commit messages, don’t you?<\/a><\/p><\/blockquote>\n Ok, glad you’re interested. Let’s get started.<\/p>\n You might use different tools for building your project: grunt, gulp, webpack or even just npm. I’ve found that the most convenient way is to hook your scripts directly into the Assume you use You can now run your build also through npm itself using Travis<\/a> is the<\/strong> continuous integration server for GitHub based projects. It has quite good docs, so you should find everything you need to get started. For JavaScript based projects start here: http:\/\/docs.travis-ci.com\/user\/languages\/javascript-with-nodejs\/<\/a>.<\/p>\n What it’ll ask you is to create a “.travis.yml” file. Here’s an example:<\/p>\n The important things to grasp here are:<\/p>\n Moreover for Travis to work properly, you have to add the <\/p>\n Finally, semantic-release<\/a>. This is an awesome library that automates<\/p>\n Just go to the main repository<\/a>. There are a couple of introductory videos, linked articles and obviously all of the instructions on how to get it up and running.<\/p>\n In the end, what you need to do is to run the semantic-release cli<\/strong> which will do the job of authorizing Travis to publish to your GitHub and npm repo and to properly setup your When you succeed to setup the before mentioned setups, you should now have<\/p>\n The last step that’s missing is to release on Bower (if you want to support that). To be honest, the fame of Bower is decreasing. People are favouring npm as most probably they’re already using it anyway for some NodeJS based backend or at least for the tooling. Nevertheless, Bower is still a reality and people are demanding for it<\/a>.<\/p>\n The problem is that Bower is not so easy to setup as NPM. It doesn’t allow to publish your binaries to a registry, but rather it works directly off your git repository. Point 1 and 2 shouldn’t be that hard to satisfy. Creating a The critical point is to push the built-files, that is, your compiled and minified JavaScript code, CSS etc., to the repository. Why’s that? Well, first of all, having generated files on master is a mess, with PR, commits and much more. Kent C. Dodds recently published a nice article on why he doesn’t commit generated files to master any more<\/a>.<\/p>\n What would have to happen is the following:<\/p>\n It’s a mess. Mostly I don’t like the idea of having an automated machine push to master. Kent C. Dodds had the same issue<\/a> and decided to solve and automate it: publish-release<\/a><\/p>\n Install the library and add it as He has an interesting solution: You know what’s best of all this. Whenever now someone sends you a PR, Travis executes the tests against the new contribution, does all the checks you’ve setup (linting whatever..) and if everything is fine, you are 1 click away from merging and releasing a new version with the new contribution<\/strong>.<\/p>\n Here are some of my repositories where I’ve already set this up, as well as others which you can use as an example to get started.<\/p>\n Besides the article I mentioned above, Kent C. Dodds<\/a> has done a lot of research on how to best create an Open Source JavaScript library and shares his knowledge in this series of Egghead.io videos<\/a>. Definitely worth watching (I’ve not done it yet… \n
![\"\"](\"https:\/\/assets.github.com\/images\/icons\/emoji\/unicode\/1f612.png\" "\\":unamused:\\"")
)<\/li>\nIssue 1: Have automated builds<\/h2>\n
Issue 2: Releasing on package repositories<\/h2>\n
Issue 3: Follow the semver spec<\/h2>\n
\nThese are the kind of thoughts going on…worse: increase the minor even if it’s a breaking change. You won’t believe, but popular libraries like Angular v1.x do that!!<\/p>\nIssue 4: Changelog<\/h2>\n
![\"\"](\"https:\/\/assets.github.com\/images\/icons\/emoji\/unicode\/1f603.png\" "\\":smiley:\\"")
. Heard about “conventional commits”<\/strong>?? If I’m not wrong, the Angular team first introduced them: read here<\/a>.<\/p>\n![\"changelog\"](\"http:\/\/www.webcodegeeks.com\/wp-content\/uploads\/2015\/10\/changelog-1024x619.png\")
<\/a><\/p>\n\n
feat(core): add undo\/redo functionality\r\n\r\nIt is now possible to undo\/redo changes applied to the model. Simply invoke...<\/pre>\n
feat(..): bla bla\r\n\r\nbla bla\r\n\r\nBREAKING CHANGE:\r\nThis is a breaking change. Before you did... now you have to ....<\/pre>\n
Love it! Show me how to get it for my lib!<\/h2>\n
Get your build scripts ready<\/h3>\n
package.json<\/code> file s.t. Travis (we’ll see later) can invoke them simply by using npm.<\/p>\ngrunt<\/code> and your build command is grunt build<\/code>. Then open your package.json<\/code> and add a “scripts” section if there isn’t one already.<\/p>\n...\r\n\"scripts\": {\r\n \"build\": \"grunt build\",\r\n \"test\": \"grunt karma:ci\",\r\n ...\r\n},\r\n...<\/pre>\nnpm run build<\/code> or npm run test<\/code>. This is required for later hooking everything up with Travis. Moreover it is nice as you can easily change your build and test commands from within this single file.<\/p>\nSetup Travis<\/h3>\n
sudo: false\r\nlanguage: node_js\r\ncache:\r\n directories:\r\n - node_modules\r\nbranches:\r\n only:\r\n - master\r\nnotifications:\r\n email: false\r\nnode_js:\r\n - '4.1'\r\nbefore_install:\r\n - npm i -g npm@^2.0.0\r\n - npm install -g grunt\r\n - npm install -g bower\r\n - npm install\r\n - bower install\r\n...<\/pre>\n
\n
branches:<\/code> this setting makes sure that only pushes to the master are being build. You can also blacklist your branches, just have a look at the official docs. Note, PR<\/em> will be build anyway, so you don’t loose that comfort.<\/li>\nbefore_script:<\/code> a series of commands to run before Travis starts building your project. In this section here you have to make sure you setup the build environment, like installing tools such as Grunt, Gulp or whatever you need.<\/li>\n<\/ul>\nprepublish<\/code> hook point.<\/p>\n...\r\n\"scripts\": {\r\n \"build\": \"grunt build\",\r\n \"test\": \"grunt karma:ci\",\r\n \"prepublish\": \"npm run build\",\r\n ...\r\n},\r\n...<\/pre>\nsemantic-release to the help<\/h3>\n
![\"semanticrelease\"](\"http:\/\/www.webcodegeeks.com\/wp-content\/uploads\/2015\/10\/semanticrelease.png\")
<\/a><\/p>\n\n
package.json<\/code> file. It’ll also add a semantic-release<\/code> step in the scripts<\/code> section of the package.json<\/code>.<\/p>\n...\r\n\"scripts\": {\r\n \"build\": \"grunt build\",\r\n \"test\": \"grunt karma:ci\",\r\n \"prepublish\": \"npm run build\",\r\n \"semantic-release\": \"semantic-release pre && npm publish && semantic-release post\"\r\n},\r\n...<\/pre>\nBower support<\/h3>\n
\n
\nBower requires you to<\/p>\n\n
bower.json<\/code> file (just like package.json<\/code>)<\/li>\nbower.json<\/code> is as simple as invoking bower init<\/code> and semantic-release will take care of creating the correct git tag.<\/p>\n\n
postpublish<\/code> task in the package.json<\/code> file:<\/p>\n...\r\n\"scripts\": {\r\n \"build\": \"grunt build\",\r\n \"prepublish\": \"npm run build\",\r\n \"postpublish\": \"publish-latest\",\r\n \"test\": \"grunt karma:ci\",\r\n \"semantic-release\": \"semantic-release pre && npm publish && semantic-release post\"\r\n},\r\n...<\/pre>\npublish-latest<\/code> creates (if it doesn’t exist) a new latest<\/code> branch where the distribution files will be placed (usually in a dist<\/code> folder). That branch will be tagged by semantic-release and then publish-latest<\/code> pushes that branch back to your GitHub repo. Hence, you’ll end up having your master<\/code> clean with just the source code and a latest<\/code> branch containing the latest, compiled and minified files to be distributed. Since the tag is on that branch, Bower will also find it easily and your users will be able to install it from there without any issues.<\/p>\nConclusion<\/h2>\n
![\"githubmerge\"](\"http:\/\/www.webcodegeeks.com\/wp-content\/uploads\/2015\/10\/githubmerge-1024x178.png\")
<\/a><\/p>\n\n
![\"\"](\"https:\/\/assets.github.com\/images\/icons\/emoji\/unicode\/1f633.png\" "\\":flushed:\\"")
).<\/p>\n