New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add npm support #793

Merged
merged 1 commit into from Dec 14, 2016

Conversation

Projects
None yet
3 participants
@dcalhoun
Contributor

dcalhoun commented Dec 5, 2016

Add package.json and npmignore to support installation of runtimes via
npm (address #711).

Add npm support
Add package.json and npmignore to support installation of runtimes via
npm (address #711).
@badlogic

This comment has been minimized.

Show comment
Hide comment
@badlogic

badlogic Dec 12, 2016

Contributor

There's no way to put this in the spine-ts folder, correct?

Contributor

badlogic commented Dec 12, 2016

There's no way to put this in the spine-ts folder, correct?

@dcalhoun

This comment has been minimized.

Show comment
Hide comment
@dcalhoun

dcalhoun Dec 12, 2016

Contributor

TL;DR

Not without publishing the source to npmjs.com. As referenced I referenced in #711, npm does not support package.json files in the subdirectory of git repos and has no plans to change that stance.

Options

  1. Place a package.json in the root of this project, allowing users to install the runtimes with npm via this GitHub repository URL. You have the option to publish or not publish to npm. This PR accomplishes this.
  2. Place package.json in the single directory you'd like to publish to npm (e.g. – spine-ts) and npm publish that directory. Users would be able to install from npm, but not from GitHub. You would need to bump the semver of the package and npm publish every time you update the source for a new release.
  3. Rather than publishing only spine-ts, you could publish all the packages to npm. You could setup Lerna to publish each of the spine-runtimes to npm individually, while retaining single repository to manage the source and all issues and pull requests.
Contributor

dcalhoun commented Dec 12, 2016

TL;DR

Not without publishing the source to npmjs.com. As referenced I referenced in #711, npm does not support package.json files in the subdirectory of git repos and has no plans to change that stance.

Options

  1. Place a package.json in the root of this project, allowing users to install the runtimes with npm via this GitHub repository URL. You have the option to publish or not publish to npm. This PR accomplishes this.
  2. Place package.json in the single directory you'd like to publish to npm (e.g. – spine-ts) and npm publish that directory. Users would be able to install from npm, but not from GitHub. You would need to bump the semver of the package and npm publish every time you update the source for a new release.
  3. Rather than publishing only spine-ts, you could publish all the packages to npm. You could setup Lerna to publish each of the spine-runtimes to npm individually, while retaining single repository to manage the source and all issues and pull requests.
@badlogic

This comment has been minimized.

Show comment
Hide comment
@badlogic

badlogic Dec 12, 2016

Contributor

We've talked about this internally. We propose the following "solution".

  1. Create spine-ts/npm, move the two files in this PR there
  2. Updated spine-ts/README.md with a section on usage via NPM. Instruct people to copy the two files in spine-ts/npm to root of their clone

We'd rather not publish the spine runtimes to NPM for a) licensing reasons and b) because we'd have to start versioning the runtimes, which we currently would rather not.

Does that work for you? Would you amend your PR accordingly or should we do it?

Contributor

badlogic commented Dec 12, 2016

We've talked about this internally. We propose the following "solution".

  1. Create spine-ts/npm, move the two files in this PR there
  2. Updated spine-ts/README.md with a section on usage via NPM. Instruct people to copy the two files in spine-ts/npm to root of their clone

We'd rather not publish the spine runtimes to NPM for a) licensing reasons and b) because we'd have to start versioning the runtimes, which we currently would rather not.

Does that work for you? Would you amend your PR accordingly or should we do it?

@dcalhoun

This comment has been minimized.

Show comment
Hide comment
@dcalhoun

dcalhoun Dec 12, 2016

Contributor

That doesn't really accomplish adding npm "support," but more so educating someone on how to fork a repository and add support themselves. I also find the stance against versioning odd, given that lack of versioning makes using and following changes to the runtimes quite difficult.

I find this form of npm "support" disappointing, as it means I, and any other follower, will have to maintain a fork of this repository pulling in the latest upstream occasionally. That said, this is all your prerogative. I appreciate the time you have invested into the runtimes. I can update the PR if you desire that format.

Contributor

dcalhoun commented Dec 12, 2016

That doesn't really accomplish adding npm "support," but more so educating someone on how to fork a repository and add support themselves. I also find the stance against versioning odd, given that lack of versioning makes using and following changes to the runtimes quite difficult.

I find this form of npm "support" disappointing, as it means I, and any other follower, will have to maintain a fork of this repository pulling in the latest upstream occasionally. That said, this is all your prerogative. I appreciate the time you have invested into the runtimes. I can update the PR if you desire that format.

@badlogic

This comment has been minimized.

Show comment
Hide comment
@badlogic

badlogic Dec 12, 2016

Contributor

I understand the frustration with versioning. The problem is that the editor version isn't fully in synch with the version of the runtime. To give a few examples:

  1. We release editor version 3.5.42, but nothing has changed in master. Should we tag master with 3.5.42 and release to NPM and other artifact repositories?
  2. The last editor version is 3.5.42. In the meantime, we add APIs to the runtimes, or fix bugs. This would either mean a minor or a patch version update. Should we publish runtime version 3.5.43 (patch) or 3.6.43 (API addition/breakage)?

Both the editor and the runtimes are updated at a very high frequency. We can't keep their respective versions in lock step. Would the user experience be better if the published versioned artifacts, with version numbers that don't line up with the editor versions?

If you have suggestions on how to deal with this issue, please let us know. We are open for feedback.

As for putting the NPM files in the root dir, I let @NathanSweet give some input on that.

Contributor

badlogic commented Dec 12, 2016

I understand the frustration with versioning. The problem is that the editor version isn't fully in synch with the version of the runtime. To give a few examples:

  1. We release editor version 3.5.42, but nothing has changed in master. Should we tag master with 3.5.42 and release to NPM and other artifact repositories?
  2. The last editor version is 3.5.42. In the meantime, we add APIs to the runtimes, or fix bugs. This would either mean a minor or a patch version update. Should we publish runtime version 3.5.43 (patch) or 3.6.43 (API addition/breakage)?

Both the editor and the runtimes are updated at a very high frequency. We can't keep their respective versions in lock step. Would the user experience be better if the published versioned artifacts, with version numbers that don't line up with the editor versions?

If you have suggestions on how to deal with this issue, please let us know. We are open for feedback.

As for putting the NPM files in the root dir, I let @NathanSweet give some input on that.

@NathanSweet

This comment has been minimized.

Show comment
Hide comment
@NathanSweet

NathanSweet Dec 12, 2016

Member

In my experience, semantic versioning doesn't work well for all projects. Often versions end up getting bumped for breakage that affects very few users, and updating a dependency is never something to be done lightly anyway.

Mario mentioned some of the difficulties with sync'ing the editor and runtime versions. Considering that, it seems the remaining options are 1) put NPM files in a spine-ts directory and users setup NPM support themselves by moving the files, or 2) put the NPM files in the root directory. Does 2 involve keeping the version in the NPM file updated? If so, we'll need to make sure we update it when we tag the repo for a particular editor version. Littering our repo root with build system files is suboptimal in general, but especially so when only spine-ts makes use of them. I suppose we've already done it for cmake, so there is precedence.

Member

NathanSweet commented Dec 12, 2016

In my experience, semantic versioning doesn't work well for all projects. Often versions end up getting bumped for breakage that affects very few users, and updating a dependency is never something to be done lightly anyway.

Mario mentioned some of the difficulties with sync'ing the editor and runtime versions. Considering that, it seems the remaining options are 1) put NPM files in a spine-ts directory and users setup NPM support themselves by moving the files, or 2) put the NPM files in the root directory. Does 2 involve keeping the version in the NPM file updated? If so, we'll need to make sure we update it when we tag the repo for a particular editor version. Littering our repo root with build system files is suboptimal in general, but especially so when only spine-ts makes use of them. I suppose we've already done it for cmake, so there is precedence.

@dcalhoun

This comment has been minimized.

Show comment
Hide comment
@dcalhoun

dcalhoun Dec 14, 2016

Contributor

@badlogic I definitely understand the pain with attempting to keep releases in lock step. Matching versions is beneficial to users, as they can be confident they are using the correct software and runtime together. However, the work to keep things in lock step is incredibly tedious for the developers.

My initial reaction is that it is OK for the versions to not match. Even if there is some confusion regarding which runtime matches a particular software, it's better than no versioning at all, in my opinion.

One idea is that you always match the major version of software and runtimes. For example, both would be currently sitting at 3.x.x. In semver, major versions represent backwards incompatible changes. If you introducing a backwards incompatible change, it's likely that both the software and runtime should be have their major release incremented. Outside of major versions, the minor and patch versions could differ between the software and runtime.


@NathanSweet I am not sure what you mean by...

Often versions end up getting bumped for breakage that affects very few users [...]

If a version is bumped for a change (as it should to make users aware), it's still the user's prerogative if they upgrade or not. If they want a patch version bug fix, they upgrade. If they don't want to deal with a major version breaking change, they wait to upgrade.

[...] updating a dependency is never something to be done lightly anyway.

Agreed, but the whole idea behind semver is that you can inform the user of the types of changes being made. Hypothetically, minor and patch version changes can be taken "lightly," if the package developer strictly adheres to semver. I'm not naive enough to believe that it's absolute truth that there will never be an issue, but that is the spirit of semver.

Does 2 involve keeping the version in the NPM file updated?

If you place the package.json in the git repo root and do not publish to npm, it is not required to keep the package.json version number up-to-date. Merely having package.json in the git repo will allow users to install the source from GitHub. Users can even target specific branches and commit shas.

Contributor

dcalhoun commented Dec 14, 2016

@badlogic I definitely understand the pain with attempting to keep releases in lock step. Matching versions is beneficial to users, as they can be confident they are using the correct software and runtime together. However, the work to keep things in lock step is incredibly tedious for the developers.

My initial reaction is that it is OK for the versions to not match. Even if there is some confusion regarding which runtime matches a particular software, it's better than no versioning at all, in my opinion.

One idea is that you always match the major version of software and runtimes. For example, both would be currently sitting at 3.x.x. In semver, major versions represent backwards incompatible changes. If you introducing a backwards incompatible change, it's likely that both the software and runtime should be have their major release incremented. Outside of major versions, the minor and patch versions could differ between the software and runtime.


@NathanSweet I am not sure what you mean by...

Often versions end up getting bumped for breakage that affects very few users [...]

If a version is bumped for a change (as it should to make users aware), it's still the user's prerogative if they upgrade or not. If they want a patch version bug fix, they upgrade. If they don't want to deal with a major version breaking change, they wait to upgrade.

[...] updating a dependency is never something to be done lightly anyway.

Agreed, but the whole idea behind semver is that you can inform the user of the types of changes being made. Hypothetically, minor and patch version changes can be taken "lightly," if the package developer strictly adheres to semver. I'm not naive enough to believe that it's absolute truth that there will never be an issue, but that is the spirit of semver.

Does 2 involve keeping the version in the NPM file updated?

If you place the package.json in the git repo root and do not publish to npm, it is not required to keep the package.json version number up-to-date. Merely having package.json in the git repo will allow users to install the source from GitHub. Users can even target specific branches and commit shas.

@NathanSweet

This comment has been minimized.

Show comment
Hide comment
@NathanSweet

NathanSweet Dec 14, 2016

Member

Semver causes major version bumps from breaking changes, even for esoteric features which affect few users or for minor breakage that is very easily remedied. I prefer version numbers that communicate the general magnitude of the differences between versions. Users need to be aware of differences when they upgrade beyond what a version number can tell them. I don't find semver helpful in practice.

It sounds like #2 is the best we can do.

Member

NathanSweet commented Dec 14, 2016

Semver causes major version bumps from breaking changes, even for esoteric features which affect few users or for minor breakage that is very easily remedied. I prefer version numbers that communicate the general magnitude of the differences between versions. Users need to be aware of differences when they upgrade beyond what a version number can tell them. I don't find semver helpful in practice.

It sounds like #2 is the best we can do.

@badlogic

This comment has been minimized.

Show comment
Hide comment
@badlogic

badlogic Dec 14, 2016

Contributor

Option #2 it is. I'll try to keep the version in the package.json as up-to-date as possible. Since we don't use NPM, it'd be nice if you could help us maintain these files @dcalhoun

Contributor

badlogic commented Dec 14, 2016

Option #2 it is. I'll try to keep the version in the package.json as up-to-date as possible. Since we don't use NPM, it'd be nice if you could help us maintain these files @dcalhoun

@badlogic badlogic merged commit a8a20fc into EsotericSoftware:master Dec 14, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment