Skip to content

Latest commit

 

History

History
228 lines (137 loc) · 9.84 KB

CONTRIBUTING.md

File metadata and controls

228 lines (137 loc) · 9.84 KB
Raw

Litvis NPM packages

Litvis as a framework for interpreting markdown documents can have multiple implementations in various programming languages. A reference implementation of litvis has been developed using TypeScript, a typed superset of JavaScript. Most of this open-source software can be found in https://github.com/gicentre/litvis → packages directory and the remaining bits are located in these repositories:

The easiest way to try litvis is to install either the Atom package or the Visual Studio Code extension.

Development

Litvis code is organised in a form of a monorepo and relies on yarn workspaces for package management. It also uses lerna for orchestrating packages in the monorepo.

Before getting started, please make sure you have the latest node and the latest yarn installed on your machine.

node --version
## ≥ 12.15

yarn --version
## ≥ 1.22

Installing dependencies

# cd gicentre/litvis
yarn

Building packages

## once
yarn build

## continuously
yarn build:watch

Publishing litvis packages manually if lerna publish has failed

## one-time password for two-factor auth
export NPM_CONFIG_OTP=??

yarn lerna exec npm publish

Registering litvis packages using yarn link for local development

yarn lerna exec yarn link

## to unregister
# yarn lerna exec --no-bail yarn unlink

Quality control

Linting

yarn lint

Testing

yarn test

Checking file formatting with Prettier

yarn format:check

Running all checks

yarn qa

yarn build-and-qa
## ‘build-and-qa‘ is recommended for ‘cold start’
## (i.e. when packages have not been built previously)

Local development pipeline and testing with Atom

This section is based on the assumption that at least one package in this repo is being worked on.

First step is to clone the three repositories (this one, plus gicentre/mume-with-litvis and gicentre/markdown-preview-enhanced-with-litvis.

Open a terminal in the folder of this repo (gicentre/litvis),

  1. Run yarn/yarn install

  2. For each package being worked on, go the folder of the package (e.g. cd packages\narrative-schema) and run npm link. This will create a symlink in a global/user node_modules folder.

  3. Back in the main folder, run yarn build:watch

Open a new terminal and navigate to the mume-with-litvis folder.

  1. Run npm install

  2. Open the node_modules folder and check the modules that are dependencies from the litvis repository (e.g. litvis-integration-mume). Now, for those packages that were linked in the previous step, run npm link package_name. For example, if working on litvis-integration-mume, run npm link litvis-integration-mume.

  3. Back in the main folder, run npm run build:watch

Lastly, open a new terminal in the markdown-preview-enhanced-with-litvis folder.

  1. Run npm install

  2. Open the node_modules folder and find modules that are dependencies from the previous two repositories (mume-with-litivs and any of the packages in this repo). For each of them, run npm link package_name as previously.

  3. Back in the main folder, run npm run build.

  4. Run apm link -d. This will create a link from the package (in the repo) to the development folder of atom.

  5. Run again npm run build:watch.

Finally, in a separate terminal, run atom -d to open the development version of Atom. This will ensure that the markdown preview litvis-enhanced package is taken from the development folder and will not conflict with the release version. Now, every time a file in this repo is changed and saved, a chain of build commands will be triggered, ensuring that the Markdown Preview package is (locally) updated. To reload Atom and the packages to actually see the changes, go to View -> Developer -> Reload Window. When committing and merging changes, don't forget to use yarn lint to pass the github checks.

Potential issues in local development

MacOS related:

  1. coreutils might be required (npm install -g coreutils).

  2. There might be a problem with fsevents when building the packages or loading Atom. npm install -g fsevents@1.2.9 and rebuilding the package when requested, in Atom, should solve it.

Releasing new versions

Publishing packages declared in gicentre/litvis

TODO

Upgrading Vega and Vega-Lite

Vega and Vega-Lite are not direct dependencies of gicentre/litvis. They are introduced downstream inside NPM package mume-with-litvis, which in turn is a dependency of Atom and VSCode extensions.

Vega, Vega-Lite and their auxiliary libraries are listed in mume-with-litvis → package.json. The versions are specified with ^, which means that the latest available patches or semver minor features will be picked automatically on extension install (or reinstall).

To upgrade development versions of vega libraries in mume-with-litvis, you need to remove them from yarn.lock and reinstall dependencies (yarn install).

If you need to upgrade major versions, e.g. vega-lite@X.Y.Z to vega-lite@[X+1].0.0, new extension releases are necessary. Please follow the steps below.

1. Produce a new version of mume-with-litvis

  1. Check out the latest commit on the main branch of https://github.com/gicentre/mume-with-litvis.git.

  2. Update versions for vega, vega-lite, vega-embed, vega-loader, apache-arrow or vega-loader-arrow in package.json.

  3. Run yarn install.

  4. Find dependentLibraryConfigs in src/markdown-engine.ts and upgrade versions accordingly. Note that you might also need to update buildPathForWebview if it has changed.

  5. In the unlikely case of breaking changes that affect the lifecycle of vega-based visualizations, consider updating additional files in src folder. This may be necessary in a small subset of cases, and only when the major versions are bumped.

  6. Update CHANGELOG.md file by adding a new ## Unreleased (minor|patch) section (example).

  7. Commit the changes.

  8. Update CHANGELOG.md again by replacing ## Unreleased (...) with a new expected version number. Stage this file.

  9. Run yarn publish --minor or yarn publish --patch. This will build mume-with-litvis from its source, change version in package.json, publish the new version on NPM, commit to main and add git tag (v*). 2FA authentication token should be asked as part of this. Beware that publishing may fail on a slow internet connection due to the size of mume-with-litvis combined with the expiration of 2FA tokens.

  10. Open https://www.npmjs.com/package/mume-with-litvis and verify that the package version has been updated.

  11. Commit your change in package.json and push both commits to the main branch on github.

You may also want to cherry-pick the first commit to mume in order to keep the fork in sync with its origin. Example pull request: shd101wyy/mume#79.

2. Produce a new version of the Atom package

  1. Check out the latest commit on the main branch of https://github.com/gicentre/markdown-preview-enhanced-with-litvis.git.

  2. Run yarn install.

  3. Run yarn install mume-with-litvis@latest to update the version of this dependency.

  4. Open CHANGELOG.md and document upcoming changes.

  5. Commit (see example) and push.

  6. Run apm publish patch or apm publish minor depending on the nature of the upstream changes. This should automatically bump the version in package.json and push a new commit to GitHub, which constitutes the release (see example). You will be asked to authenticate at APM if needed.

  7. Push the main branch.

The new package version should now show up in Atom and it should be possible to upgrade. If the new version ends up broken, you can rollback by running apm install markdown-preview-enhanced@another-version.

3. Produce a new version of the VSCode extension

  1. Make sure you have the latest version of vsce installed globally.

    npm install -g vsce

  2. Check out the latest commit on the main branch of https://github.com/gicentre/vscode-markdown-preview-enhanced-with-litvis.git.

  3. Run yarn install.

  4. Run yarn install mume-with-litvis@latest to update the version of this dependency.

  5. Open CHANGELOG.md and document upcoming changes.

  6. Commit (see example) and push.

  7. Run vsce publish patch or vsce publish minor depending on the nature of the upstream changes. You will be asked to authenticate at Visual Studio Marketplace if needed.

  8. Push the main branch.