What is a good rule of thumb to write dependencies in package.json or Gemfile, and semantic versioning

A good rule of thumb is, specify the version that can pull the latest version, but is backward compatible with earlier versions, so that we get small updates and bug fixes, but not a version that can break our project.

The version number has a meaning. And it is written by the founder and CEO of GitHub, so we may want to take a look.

In package.json:

"react": "^16.14.0",

The ^ means "compatible". In the above case, it means 16.x.x, but not 17.0.0, because 17.0 may break our project, and we want to be careful about it. (that's why in the Gemfile case below, the operator is called a "pessimistic operator".) If a programmer is optimistic, it can be written as

"react": ">=16.14.0",

which means 16.14.0 or above, including 17.0 or 23.0. That might be "too optimistic".

More reference: package.json dependencies.

In a Gemfile:

gem 'sqlite3', '~> 1.4'

The ~> has 3 names: pessimistic operator, twiddle-wakka, and eating bacon.

Note that the first character is a tilde:

In some font, it can look like a hyphen.

The above means 1.x.x, but not 2.0.0.

Note that we can't write

gem 'sqlite3', '~> 1.4.0'

to mean the same thing. Because that means in Gemfile: "1.4.x but not 1.5.0."

In a Gemfile, to achieve what package.json is doing, it can be:

gem 'sqlite3', '~> 1.4', '>= 1.4.1'

meaning at least 1.4.1 and 1.x but not 2.0. The reason we want to be specific about 1.4.1 may be due to a bug fix in 1.4.1 or any other reasons.

Reference: dependencies in Gemfile.