Compiling documentation for npm module => Rails app workflow

[jywarren]

I discussed this with @Tlazypanda and looking to get some good docs together so we can guide people helpfully through this process!

Thinking a diagram may be really useful, but there are 2 repositories:

• the upstream library (which does a narrow set of things but has a general purpose scope, even if its main or only use is the downstream app)
• the downstream application (which uses the upstream library like a utility, to accomplish a narrow purpose)
• there are also any other potential downstream apps or libraries which may also use (and depend on) the upstream library, which you can often see on a page like this: https://github.com/publiclab/Leaflet.DistortableImage/network/dependents

Here are the steps to bringing new changes all the way from the original upstream library to the downsteam application and publishing them to the live site:

• Make code changes in upstream library
• Decide if we want to release a new version on NPM (which would make the new changes available in a downstream application)
• Decide if the changes since the last release are a Major, Minor, or Patch release, using Semantic Versioning: https://docs.npmjs.com/about-semantic-versioning
• Change the version number in package.json file and run npm install to ensure it updates package-lock.json (although maybe npm doesn't completely care about this?)
• Run npm publish (only NPM package "collaborators" can do this; see them on an npmjs.org page like https://npmjs.com/package/publiclab-editor)
• Check that the npmjs page (like https://npmjs.com/package/publiclab-editor) updates to show the new version
• Now, in the downstream application, get Dependabot to bump the version using the button/link at: https://github.com/publiclab/plots2/network/updates (this could also be done manually with gem update gem_name in a new PR)
• Watch if the tests all pass; if they don't, DON'T merge the PR - fix it upstream! (exception: if you've purposely introduced and documented breaking changes, and it's a Major version upgrade (don't do this too often, because all downstream users will have to fix things to get this upgraded version!)
• If everything passes and the new feature works, merge the PR!
• Publish to the live site!

I probably missed something in this list, if only documentation or explanation of some terms... help me refine and expand this guide!!!

[jywarren]

Let's also keep in mind that some NPM modules are included into other NPM modules, so you have to do this cycle 2x -- 😭 -- like with https://github.com/jywarren/woofmark => https://github.com/publiclab/PublicLab.Editor/ => https://github.com/publiclab/plots2/

[Tlazypanda]

Found this pretty detailed article covering everything: https://formidable.com/blog/2020/publish-npm-packages/

[Tlazypanda]

Found this awesome tool as well to make the publishing process simpler - https://github.com/sindresorhus/np
cc @jywarren @TildaDares

[unnati914]

could I work on this?

[bhargavi30-dsa]

Hi! I'm a new contributor and I'd like to work on this issue.
Could you please assign it to me? Thank you!

[sinanAk16822]

“Hello! I’m interested in working on this issue.
This will be my first contribution here.
Please let me know if I can proceed.

[hariprabhu571]

can you assign this to me?