Skip to content

z OLD Procedures for publishing packages

Z3 Development edited this page Sep 26, 2021 · 1 revision

These instructions are mostly useful for admins of the project , but they also allow to do thing transparently

The aim is to fully automate things at some (near future) point, in order to remove any risk of errors and accidents.

Note: this applies to pretty much all of the packages/repositories in the jscad organization, except for 'io' as that one is a 'metapackage' ie you need to deal with the individual packages within it (packages folder) in the same way as outlined here

Note2: DO NOT change the name or version number of the package in package.json without consulting with the other persons on the team first, it could break things really badly !

Merging Pull Requests (PR)

  • any new feature , bug fix , etc can ONLY go through PRs
  • only PRs with passing tests should be accepted !
  • if there are changes to the tests it should be made clear how/what they impact
  • a PR should ideally only deal with one problem or feature : this is not always convenient/possible, but should be a rule to strive for as much as possible: a PR can only have ONE predominant aspect: ie if there is a fix & a feature, it is a feature PR (think semantic versioning)
  • You should always use the squash and merge method for merging PRs : this allows to have only a SINGLE commit represent a new feature or a fix etc, instead of x commits during the lifespan of the PR.
  • Those final commit messages need to be one of the following:(based on a lot of projects using it, original created by the Angular project : read more here

This describes the kind of change that this commit is providing.

  • feat (feature)
  • fix (bug fix)
  • docs (documentation)
  • style (formatting, missing semi colons, …)
  • refactor
  • test (when adding missing tests)
  • chore (maintain)

this level of standardisation (trust me you get used to it fast) in turn will allow for automatic detection of WHAT happened in a given PR, for automatic changelog generation, etc

After PR merging

an accepted and merged PR means something has changed, and thus a new version should be created

Create a new version

  • first get the latest updated version of the MASTER branch onto your local MASTER branch git checkout master && git pull upstream master
  • all packages have a package.json file with scripts to create new versions: it is VERY important to respect semantic versioning: Do NOT manually change the version numbers of packages , as it could result in incoherent version numbers
  • if there was only a bugfix , increase the PATCH version (ie 1.0.0 => 1.0.1) use the npm run release-patchcommand from the command line
  • if there was a minor change (non breaking , backward compatible api change) , increase the MINOR version (ie 1.0.0 => 1.1.0) use the npm run release-minorcommand from the command line
  • if there was a major change (breaking , NOT backward compatible api change) , increase the MAJOR version (ie 1.1.0 => 2.0.0) use the npm run release-majorcommand from the command line

All the release commands above will do the following: (some background can be found here)

  • run the tests
  • if the tests pass: (if not , the script just stops with an error message)
    • update the version number
    • run any build operation if needed, add the built/compiled files (git add -A) so now the prebuilt files include the updated version number
  • git tag the release (so it can be visible in the list of releases , etc)
  • push the code to master, and the tags as well

IMPORTANT this does NOT push the new release to npm !

Publishing to NPM

Preamble

In order to be able to publish to NPM you

Publishing the package itself

  • go to the folder of the package that you want to publish
  • type npm publish --access public
  • voila ! the package is now on npm

note: you cannot publish packages with existing version numbers or override existing versions !