Skip to content

Commit ac2ddb6

Browse files
committed
chore: update npm versioning notes
1 parent ba5bad5 commit ac2ddb6

File tree

1 file changed

+13
-1
lines changed

1 file changed

+13
-1
lines changed

Diff for: understanding-packages.md

+13-1
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,9 @@ There are also quite a number of plugins maintained and developed by the NativeS
3838

3939
NativeScript packages do not follow Semantic Versioning for a particular reason. Since NativeScript enables the empowerment of JavaScript with native platform APIs we strive to do major releases around platform API tooling upgrade cycles (Things like Xcode, Android Studio, etc.). Major/Minor releases are generally released every six months (~March and ~September which is often the timeframe platform API toolchains are also updated), while patch releases may be released as often as every week. Patch releases should never contain breaking changes, however minor and major releases can. We strive to always note any breaking changes in the Changelogs, to make upgrades as easy as possible.
4040

41-
We always recommend using `~` (tilda) with any NativeScript package versions in your projects as that will ensure anytime you execute a `ns clean` against your project that the next run will pull down the latest patch release fixes to anything we may have released.
41+
### Recommended: Use tilde `~`
42+
43+
We always recommend using tilde `~` with any NativeScript package versions in your projects to ensure anytime you execute `ns clean` against your project that the subsequent run will pull down the latest patch release fixes to anything we may have released.
4244

4345
For example, when referencing the `@nativescript/*` packages, we always recommend the following:
4446

@@ -55,3 +57,13 @@ For example, when referencing the `@nativescript/*` packages, we always recommen
5557
```
5658

5759
This will ensure bug fix patch updates are automatically installed when cleaning your projects in addition to ensuring that no major version changes may accidentally pulled it which may contain breaking changes.
60+
61+
### When to use caret `^`?
62+
63+
If you are comfortable with the particular npm package and are Ok handling any potential breaking changes from dependencies in your projects on your own then using a caret in front of your versions is absolutely fine.
64+
65+
[Learn more about version specifiers here](https://github.com/npm/node-semver#tilde-ranges-123-12-1)
66+
67+
### When to use `next`?
68+
69+
Using `next` as the version for any NativeScript related packages will always pull down latest `main` (or `master`) changes from the repo which is likely to contain breaking changes however can be a great way to try out cutting edge features or fixes. Use `next` when you absolutely know what you are doing.

0 commit comments

Comments
 (0)