1 | # next-update v0.9.5
|
2 |
|
3 | > Tests if module's dependencies can be updated to the newer version without breaking the tests
|
4 |
|
5 | [![NPM][next-update-icon] ][next-update-url]
|
6 |
|
7 | [![Build status][next-update-ci-image] ][next-update-ci-url]
|
8 | [![Circle CI][circle-ci-image] ][circle-ci-url]
|
9 | [![Coverage Status][next-update-coverage-image] ][next-update-coverage-url]
|
10 | [![dependencies][next-update-dependencies-image] ][next-update-dependencies-url]
|
11 | [![devdependencies][next-update-devdependencies-image] ][next-update-devdependencies-url]
|
12 |
|
13 | [next-update-icon]: https://nodei.co/npm/next-update.png?downloads=true
|
14 | [next-update-url]: https://npmjs.org/package/next-update
|
15 | [next-update-ci-image]: https://travis-ci.org/bahmutov/next-update.png?branch=master
|
16 | [next-update-ci-url]: https://travis-ci.org/bahmutov/next-update
|
17 | [next-update-coverage-image]: https://coveralls.io/repos/bahmutov/next-update/badge.png
|
18 | [next-update-coverage-url]: https://coveralls.io/r/bahmutov/next-update
|
19 | [next-update-dependencies-image]: https://david-dm.org/bahmutov/next-update.png
|
20 | [next-update-dependencies-url]: https://david-dm.org/bahmutov/next-update
|
21 | [next-update-devdependencies-image]: https://david-dm.org/bahmutov/next-update/dev-status.png
|
22 | [next-update-devdependencies-url]: https://david-dm.org/bahmutov/next-update#info=devDependencies
|
23 | [circle-ci-image]: https://circleci.com/gh/bahmutov/next-update.svg?style=svg
|
24 | [circle-ci-url]: https://circleci.com/gh/bahmutov/next-update
|
25 |
|
26 |
|
27 |
|
28 | [![asciicast](https://asciinema.org/a/21645.png)](https://asciinema.org/a/21645)
|
29 |
|
30 | Also check out:
|
31 |
|
32 | * [next-updater](https://github.com/bahmutov/next-updater) can update all your repos
|
33 | * [dont-break](https://github.com/bahmutov/dont-break)
|
34 | that checks if your code is going to break everyone who depends on it.
|
35 | * [changed-log](https://github.com/bahmutov/changed-log) returns commit messages for
|
36 | the given NPM package or Github repo between two tags.
|
37 |
|
38 | ### Example
|
39 |
|
40 | Imagine your nodejs module *foo* has the following dependencies listed in *package.json*
|
41 |
|
42 | "dependencies": {
|
43 | "lodash": "~1.2.0",
|
44 | "async": "~0.2.5"
|
45 | }
|
46 |
|
47 | You would like to update lodash and async to latest versions, to not sure if
|
48 | this would break anything. With *next-update* it is easy: run command `next-update`
|
49 | in the folder with module *foo*. Here is the example output:
|
50 |
|
51 | next updates:
|
52 | lodash
|
53 | 1.2.1 PASS
|
54 | async
|
55 | 0.2.6 PASS
|
56 | 0.2.7 PASS
|
57 | 0.2.8 PASS
|
58 |
|
59 |
|
60 | Both *package.json* file and *node_modules* folder are left unchanged,
|
61 | and now you know that you can safely upgrade both libraries to later versions.
|
62 |
|
63 | #### It even tells you the install command ;)
|
64 |
|
65 | Use the following command to install working versions
|
66 | npm install --save lodash@2.1.0
|
67 |
|
68 | This might not appear like a big deal for a single module that is using
|
69 | popular 3rd party libraries with stable apis only. *next-update* is most useful
|
70 | in the larger development context, where multiple modules are being developed
|
71 | side by side, often by different teams. In such situations, checking if an upgrade
|
72 | is possible could be part of the continuous build pipeline.
|
73 |
|
74 | You can see if your dependencies are out of date by using
|
75 | [david](https://david-dm.org),
|
76 | it even has badges you can add to your README files.
|
77 |
|
78 | *next-update* reports the probability of success for a given dependency update using
|
79 | anonymous global statistics from [next-update](http://next-update.herokuapp.com/) server
|
80 |
|
81 | ```
|
82 | available updates:
|
83 | package available from version average success % successful updates failed updates
|
84 | -------------------- --------- ------------ ----------------- ------------------ --------------
|
85 | grunt-contrib-jshint 0.8.0 0.7.2 100% 34 0
|
86 | grunt-bump 0.0.13 0.0.12 100% 4 0
|
87 | ```
|
88 |
|
89 | ### Install
|
90 |
|
91 | npm install -g next-update // installs module globally
|
92 | next-update --help // shows command line options
|
93 |
|
94 | ### Anonymous usage collection
|
95 |
|
96 | After testing each module A upgrade from version X to Y, *next-update* sends
|
97 | anonymous result to [http://next-update.herokuapp.com/](http://next-update.herokuapp.com/).
|
98 | The only information transmitted is:
|
99 |
|
100 | ```json
|
101 | {
|
102 | "name": "lodash",
|
103 | "from": "1.0.0",
|
104 | "to": "2.0.0",
|
105 | "success": true
|
106 | }
|
107 | ```
|
108 |
|
109 | This information is used to answer the following questions later:
|
110 | what is the probability module A can be upgraded from X to Y?
|
111 | Thus even if you do not have tests covering this particular module,
|
112 | you can judge how compatible version X and Y really are over the entire
|
113 | internet.
|
114 |
|
115 | You can inspect data send in
|
116 | [stats.js](https://github.com/bahmutov/next-update/blob/master/src/stats.js).
|
117 |
|
118 | If the dependency module has been upgraded by anyone else, its statistics
|
119 | will be displayed with each test.
|
120 |
|
121 | ```sh
|
122 | stats: deps-ok 0.0.7 -> 0.0.8 success probability 44.44% 8 success(es) 10 failure(s)
|
123 | ```
|
124 |
|
125 | A lot of NPM modules [do not have tests](http://npmt.abru.pt/), but
|
126 | at least you can judge if someone else has success going from verion X to version Y
|
127 | of a dependency.
|
128 |
|
129 | ### Use
|
130 |
|
131 | Make sure the target module has unit / integration tests,
|
132 | and the tests can be run using `npm test` command.
|
133 |
|
134 | Run `next-update` from the command line in the same folder as
|
135 | the target module. In general this tool does the following:
|
136 |
|
137 | 1. Reads the module's dependencies (including dev) and their versions
|
138 | 2. Queries npm registry to see if there are newer versions
|
139 | 3. For each dependency that has newer versions available:
|
140 | 1. Installs each version
|
141 | 2. Runs command `npm test` to determine if the new version breaks the tests
|
142 | 3. Installs back the current version.
|
143 | 4. Reports results
|
144 |
|
145 | #### Misc
|
146 |
|
147 | * To see what has changed in the latest version of any module,
|
148 | use my companion tool [changed](https://npmjs.org/package/changed)
|
149 | like this `changed foo` (*foo* is package name)
|
150 | * When comparing versions, keywords *latest* and *** are both assumed to equal to "0.0.0".
|
151 | * A good workflow using *next-update*
|
152 | * see available new versions `next-update --available`
|
153 | * check latest version of each module using `next-update --latest`
|
154 | * install new versions of the desired modules using standard `npm i dependency@version --save`
|
155 | * You can use custom test command, for example `next-update -t "grunt test"`
|
156 | * `npm test` is used by default.
|
157 | * You can keep each working version in package.json by using `--keep` flag.
|
158 |
|
159 |
|
160 |
|
161 | ## Development
|
162 |
|
163 | Edit source, run unit tests, run end to end tests and release
|
164 | new version commands:
|
165 |
|
166 | ```sh
|
167 | npm test
|
168 | npm run e2e
|
169 | grunt release
|
170 | npm publish
|
171 | ```
|
172 |
|
173 |
|
174 | ### Related
|
175 |
|
176 | * [Painless modular development](http://glebbahmutov.com/blog/modular-development-using-nodejs/)
|
177 | * [Really painless modular development](http://glebbahmutov.com/blog/really-painless-modular-development/)
|
178 |
|
179 |
|
180 |
|
181 | ### 3<sup>rd</sup> party libraries
|
182 |
|
183 | * [lazy-ass](https://github.com/bahmutov/lazy-ass) and
|
184 | [check-more-types](https://github.com/kensho/check-more-types) are used to
|
185 | [defend against runtime errors](http://glebbahmutov.com/blog/lazy-and-async-assertions/).
|
186 | * [lo-dash](https://github.com/bestiejs/lodash) is used to deal with collections / iterators.
|
187 | * [check-types](https://github.com/philbooth/check-types.js) is used to verify arguments through out the code.
|
188 | * [optimist](https://github.com/substack/node-optimist) is used to process command line arguments.
|
189 | * [request](https://npmjs.org/package/request) is used to fetch NPM registry information.
|
190 | * [semver](https://npmjs.org/package/semver) is used to compare module version numbers.
|
191 | * [q](https://npmjs.org/package/q) library is used to handle promises. While developing this tool,
|
192 | I quickly ran into problems managing the asynchronous nature of fetching information, installing multiple modules,
|
193 | testing, etc. At first I used [async](https://npmjs.org/package/async), but it was still too complex.
|
194 | Using promises allowed to cut the program's code and the complexity to very manageable level.
|
195 | * [cli-color](https://npmjs.org/package/cli-color) prints colored text to the terminal.
|
196 |
|
197 |
|
198 |
|
199 | ### Small print
|
200 |
|
201 | Author: Gleb Bahmutov © 2014
|
202 |
|
203 | * [@bahmutov](https://twitter.com/bahmutov)
|
204 | * [glebbahmutov.com](http://glebbahmutov.com)
|
205 | * [blog](http://glebbahmutov.com/blog)
|
206 |
|
207 | License: MIT - do anything with the code, but don't blame me if it does not work.
|
208 |
|
209 | Spread the word: tweet, star on github, etc.
|
210 |
|
211 | Support: if you find any problems with this module, email / tweet /
|
212 | [open issue](https://github.com/bahmutov/next-update/issues?state=open) on Github
|
213 |
|
214 |
|
215 |
|
216 | ## MIT License
|
217 |
|
218 | Copyright (c) 2014 Gleb Bahmutov
|
219 |
|
220 | Permission is hereby granted, free of charge, to any person
|
221 | obtaining a copy of this software and associated documentation
|
222 | files (the "Software"), to deal in the Software without
|
223 | restriction, including without limitation the rights to use,
|
224 | copy, modify, merge, publish, distribute, sublicense, and/or sell
|
225 | copies of the Software, and to permit persons to whom the
|
226 | Software is furnished to do so, subject to the following
|
227 | conditions:
|
228 |
|
229 | The above copyright notice and this permission notice shall be
|
230 | included in all copies or substantial portions of the Software.
|
231 |
|
232 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
233 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
|
234 | OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
235 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
|
236 | HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
237 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
238 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
239 | OTHER DEALINGS IN THE SOFTWARE.
|
240 |
|
241 |
|