ProteinPaint Workspaces - stjude/proteinpaint GitHub Wiki

Rationale

The proteinpaint codebase is a "monorepo" (a single git repo) containing multiple npm package codebases that are specified in the "workspaces": [...] entry of proteinpaint/package.json. By having workspaces in the same git repo, development and testing becomes simpler as the project's different workspaces can by npm-linked and share common dependencies in proteinpaint/node_modules.

The main reasons to convert code directories into a separate workspace are:

  • to be able to release the workspace separately for different use cases, such as being able to bundle proteinpaint-client in either proteinpaint-front or gdc-frontend-framework
  • to clarify the build steps for a workspace, especially for workspaces that generate compiled binaries and/or where a separate docker image build process would improve the server or full docker build workflow
  • to group code files and dependencies by programming language: by extracting Python, R, Rust code from nodejs into their own workspaces, the applicable best practice and coding conventions can be more strictly enforced and made obvious within the same workspace directory

Creating a new workspace

Create a new workspace directory

Create a new directory for the workspace in the proteinpaint repo: proteinpaint/new_workspace

Create index.js

Create an index.js file in the workspace directory that will be used as a module for calling source code of the workspace from NodeJS

Create package.json

Create a package.json file in the workspace directory that will be used to convert the workspace directory to an npm package.

version

The new workspace version has to be <= the current version in proteinpaint/package.json. If the directory to be extracted into a new workspace was under an existing workspace, it should equal the version in the "parent" workspace package.json. Later as part of a release, if relevant code in the new workspace has changed, build/bump.js will automatically match its version to the updated proteinpaint release version.

license

Copy proteinpaint/LICENSE into the new workspace dir, add a "license": "SEE LICENSE IN ./LICENSE" entry to its package.json and "LICENSE" to the "files": [...] entry so that the license will be included in the published npm package.

scripts

In general, there should be these familiar npm run ... commands to help with developer and test workflows:

  • "dev": usually involves bundling
  • "test": how to run tests
  • "prepack": generate artifacts to include in a package tarball when publishing a workspace
  • "build": usually involves bundling but for prod (such as being minified)

Update code outside workspace

Update containter/pack.sh

Add a new code block to containter/pack.sh for the new workspace. Use a code block from another workspace as a template.

Update package.json in sjpp, pp, and server

Add the new workspace to the workspaces[] array in package.json in the sjpp and proteinpaint repos. Add the new workspace to the dependencies{} object in package.json in the proteinpaint/server workspace.