Developer documentation

Install

shell cd some-empty-dir git clone https://github.com/zenodraft/zenodraft . git checkout -b <new branch> npm install

npm run scripts

Clean up generated code from previous builds:

shell npm run clean

Install dependencies:

shell npm run install

Transpile the TypeScript code from src/ to dist/ as CommonJS modules (dist/**/*.js) and as ES6 modules (dist/**/*.mjs):

shell npm run build

Package the contents from dist/ into a distributable tarball:

shell npm pack

All of the above (clean, install, build, pack):

shell npm run all

Testing

We use Jest for testing. Run the tests with

```

all tests

npm run test

individual test

npm run test tests/lib/file/add.test.ts

tests with coverage

npm run coverage ```

Many tests use mocking to simulate server replies. Our mocking library is Nock. Typically, tests that use mocking will insert simulated server replies using a pre-recorded reply from the ./mocks directory.

Local testing of the cli from the package

Assert tarball zenodraft-x.y.z.tgz has been created with npm pack.

``` cd $(mktemp -d --tmpdir zenodraft.XXXXXX) npm install path/to/the/tarball/zenodraft-x.y.z.tgz --force # --force overrides caching

you should now have a cli program node_modules/.bin/zenodraft, see if it's working

npx zenodraft npx zenodraft --version npx zenodraft --help echo -e '{ "creators": [ { "name": "Lastname, Firstname" } ], "title": "My deposition" }' > .zenodo.json npx zenodraft metadata validate .zenodo.json # should be quiet ```

Local testing of the functionality from the package

Using CommonJS require

Make a file e.g. index.js with the following contents:

javascript // file: index.js const zenodraft = require('zenodraft'); console.info(zenodraft);

shell node index.js

Should show something like:

shell { deposition_create_concept: [Getter], deposition_create_version: [Getter], deposition_delete: [Getter], deposition_publish: [Getter], deposition_show_details: [Getter], deposition_show_draft: [Getter], deposition_show_files: [Getter], deposition_show_prereserved: [Getter], file_add: [Getter], file_delete: [Getter], helpers_get_access_token_from_environment: [Getter], helpers_get_api: [Getter], metadata_update: [Getter], metadata_validate: [Getter] }

Using ES6 import

Make a file e.g. index.mjs with the following contents (you may use a different filename but the extension needs to be .mjs):

javascript // file: index.mjs import zenodraft from 'zenodraft'; console.info(zenodraft);

shell node index.mjs

Should show the same as listed above for require.

For maintainers

Order of publishing

1. Preparation
2. Zenodo
3. GitHub
4. NPM

Preparation

Before you begin, make sure that

1. everything that needs to be part of the release has been pushed to GitHub and has been merged into the default branch main.
2. the citation metadata (e.g. dates, version, contributors) has been updated (check CITATION.cff and .zenodo.extras.json)
3. the version indicators are consistent throughout the whole directory tree, e.g.
   • CITATION.cff
   • Dockerfile
   • package-lock.json
   • package.json
   • README.md
   • src/cli.ts
   • tests/cli.test.ts
   • possibly other files

Then, follow the steps below.

```shell

Uninstall any globally installed versions of zenodraft

npm uninstall -g zenodraft

Check that it's gone, should return empty

which zenodraft

Delete any environment variables that store Zenodo / Zenodo Sandbox tokens

unset ZENODOACCESSTOKEN unset ZENODOSANDBOXACCESS_TOKEN

Make a temporary directory, change into it

cd $(mktemp -d --tmpdir zenodraft-preparation.XXXXXX)

Clone the repo in the empty temporary directory

git clone https://github.com/zenodraft/zenodraft .

Install dependencies, generate the JavaScript, package it up into a tarball

npm run all

Verify the tarball has the right set of files

less zenodraft-*.tgz

Make a new temporary directory

cd $(mktemp -d --tmpdir zenodraft-testing.XXXXXX)

Install zenodraft globally using the tarball we just made

npm install -g ../zenodraft-preparation.XXXXXX/zenodraft-*.tgz

Source the autocomplete script

TMPFILE=$(mktemp) zenodraft-autocomplete > $TMPFILE source $TMPFILE ```

1. Test whether the autocomplete functionality works correctly (see section Autocomplete from README.md).
2. Test whether CLI commands work as expected (see section CLI usage from README.md).
3. Test whether zenodraft can be used as a library (see section Library usage from README.md).

Publishing to Zenodo

Manually triggering the publishing.yml workflow will send a snapshot of the repository to Zenodo. As part of the process, the workflow will also update the citation metadata with the prereserved DOI that Zenodo supplies, and commit it back to the repository.

Once the workflow finishes, log in to Zenodo to publish the deposition there.

Publishing to GitHub

After the publishing workflow from the previous step finishes, check that the DOI has been updated, then use GitHub's Draft a new release button to make a release.

Publishing to NPM

```shell

Go back to the directory with the tarball

cd ../zenodraft-preparation.XXXXXX/zenodraft-*.tgz

Log out of npm

npm logout

Choose your identity and log in to npm

npm login

FINAL STEP, THERE IS NO UNDO: publish the tarball to npmjs.com

npm publish zenodraft-*.tgz ```