Developing NCIDS - NCIOCPL/ncids GitHub Wiki

Adding a "common" dependency

yarn add new-dependency [--dev]

Linking sister repositories as dependencies

lerna add @my-scope-name/dependency-name --scope=@my-scope-name/package-using-dependency

Removing a global dependency

If there’s a dependency that all packages use but that you want to remove, Lerna has the exec command that runs an arbitrary command in each package. With this knowledge, we can use exec to remove a dependency on all packages.

lerna exec -- yarn remove dep-name

Referencing ncids-css in other packages in this repo

NCIDS uses uswds, and therefore references uswds/dist/scss/**/somefile in its scss files. Sass is smart enough to be able to find the package in node_modules, but you just need to help it a bit. You can do this by passing an array of search paths to the includePaths setting of sass. Our uswds has been hoisted to the root node_modules. It should be also noted that if you want to reference @nciocpl/ncids-css you also need to have the root node_modules in the search paths, so score. Assuming you are calling sass from the root of your package, raw sass config looks like:

includePaths: [
	path.join(__dirname, '../../../node_modules/@nciocpl/ncids-css/packages'), // ncids-css custom packages
	path.join(__dirname, '../../../node_modules/@nciocpl/ncids-css/uswds-packages'), // unaltered uswds packages available in NCIDS
],

SPECIAL NOTE: the webpack sass-loader only knows how to pass .scss file to sass. Sass still need to have the includePaths setup on it, and this is separate from webpack resolution. A great example of this is in ncids-css itself.

	{
		loader: 'sass-loader',
		options: {
			sassOptions: {
				includePaths: [
					path.join(__dirname, '../../../node_modules/@nciocpl/ncids-css/packages'),
					path.join(__dirname, '../../../node_modules/@nciocpl/ncids-css/uswds-packages'),
				],
			},
		},
	},

There is an open TODO to figure out how this all might work from an external repo consuming our package.

Patching USWDS

[!CAUTION] Patch files do not merge! So if you are rebasing from develop, and a recent commit modified the patch, you must throw away your patch and redo the patching steps.

  1. pnpm patch @uswds/uswds
    • this gives you an ugly folder path like /private/var/folders/50/y2s8mn4540g0sj58k355gp780000gn/T/caa7c17e9cbef727eaec7f67f8b67069 where you need to edit.
  2. Open the resulting folder in your editor and make changes
    • You can't test the changes until you commit them.
  3. pnpm patch-commit '<horrible folder name>'
    • The root package.json file should not be modified.
    • The pnpm-lock.yml should change, but only to reflect that the contents of the patch changed. (i.e. the hash changed)
      • Technically, when the lock is being updated, bug fix versions can be bumped. So the admin reviewing should determine if it is ok.

Publishing

Publishing a Pre-release Version

You must be added to the NCIOCPL organization and be logged in in order to publish a new package.

npm login:

  • Log in with 
    npm login --scope=@NCIOCPL --registry=https://npm.pkg.github.com
  • You can test if you are already logged in with 
    npm whoami --scope=@NCIOCPL --registry=https://npm.pkg.github.com

Creating a new version

From ncids root:

  1. Make sure branch is up to date with remote

    git pull --rebase

  2. Version release, where X, Y, Z and DD are numbers. Whatever this is, it must be unique.

    lerna version --no-git-tag-version X.Y.Z-alpha.DD
    • Select Custom Version
    • Type the new version, bump current version via semantic versioning

  3. Publish package

    lerna publish --dist-tag alpha --force-publish --no-push --yes from-package

    NOTE: This will update the package.json files everywhere. Try not to commit those changes - we don't want a bunch of commits littering our history just for beta version bumps.

  4. Commit the files temporarily. DO NOT PUSH.

  5. When publishing is complete, updated packages will be available at https://github.com/orgs/NCIOCPL/packages?tab=packages&q=ncids

Publishing for Prod Release

Publishing Steps for Prod Release

  1. Prep the release branch (NOTE: You must have push access for release branches)
    1. Checkout develop
    2. git checkout -b release/vX.Y.Z
      • Where vX.Y.Z is an actual version number, e.g., v1.2.3. (This should be greater than whatever the current version is)
    3. lerna version --no-git-tag-version X.Y.Z
      • NOTE There is no v at the beginning of the version!!
    4. Update version element in the root package.json to reflect the new number
      • Lerna version will not bump it.
    5. Review the changes to the package.json and lerna.json files to make sure it is only version bumping.
      • So this looks like it will change workspace: * to workspace:X.Y.Z. This should be changed back to workspace: * and a pnpm install must be run to update the lockfile (which then should end up showing 0 changes)
    6. git commit -am "Bumping package for vX.Y.Z"
    7. git push -u origin release/vX.Y.Z
  2. Build and Test a Beta Package.
    1. Clone the repo to a new location.
    2. git checkout release/vX.Y.Z
    3. pnpm install
    4. lerna version --no-git-tag-version X.Y.Z-beta.N where X.Y.Z are the version number in the lerna.json and N is the next beta for the release, starting with 1. E.g., 1.2.3-beta.1
    5. git commit -am "trash commit"
      • DO NOT PUSH THIS COMMIT! However, lerna publish won't publish with outstanding commits.
    6. lerna publish --dist-tag beta --force-publish --no-push --yes from-package
      • The package should show in github after a few minutes.
    7. Delete your clone.
    8. Test. Apply bug fixes to release branch. Repeat.
  3. Merge the release to main
    1. Checkout main
      • git checkout main
    2. Make sure you are up to date
      • git pull
    3. Merge the release branch
    • git merge --no-ff release/vX.Y.Z -m "Merging release vX.Y.Z"
    1. Push the main branch
      • git push
    2. Create the release
      • hub release create -t release/vX.Y.Z -m "vX.Y.Z Release" vX.Y.Z
  4. Publish the packages. This uses the version from all the package.json files and avoids running lerna version, as well as skip pushing a commit. I.E. It just publishes.
    • lerna bootstrap -- --frozen-lockfile
    • lerna publish --force-publish --no-push --yes from-package
  5. Merge to develop (NEED TO BE ADMIN)
    1. Checkout develop
      • git checkout develop
    2. Make sure you are up to date
      • git pull
    3. Merge the release branch
    • git merge --no-ff release/vX.Y.Z -m "Merging release vX.Y.Z"
    1. Push the main branch
      • git push
  6. Remove the release branch.
  7. Generate release notes
    1. Navigate to the Releases page
    2. Click on 'Edit' icon
    3. Click 'Generate Release Notes' Button and Save