zotero-plugin/README.md

Zotero plugin builder

# zotero-plugin

Utility scripts for releasing zotero plugins on github. See also https://github.com/retorquere/generator-zotero-plugin/

zotero-plugin-release will release your plugin as a github release.
When it is ran on master/main, and it detects a tagged build in a Github Action,
it will issue a new release. When it is ran on a branch named
`gh-<number>`, it will publish the plugin to a pre-release named
`builds`, and will announce the new build on issue number `<number>`
in your repo.

For this to work you must have a variable named `GITHUB_TOKEN` in
your GH Actions environment with a github token with `repo` rights. You
are allowed one bot account by github; I use this to do the
announcements, but you can use one from your own account if you
want.

The release script will create two releases if they don't exist;
`builds` for temporary builds, mostly for debugging, and `release`
for the update.rdf, which needs to be at a stable URL for plugin
updates to work.

If you're doing a push on a branch named `gh-<number>` but you do
not want the build to be announced, include `#norelease` in the
commit message. If you want to announce on other issues in addition
to the current branch (or maybe your branch isn't named `gh-<number>`,
add `#<number>` to the commit message.

## Releasing a new version

Add the folowing to your `scripts` section in `package.json`:

```
"postversion": "git push --follow-tags",
```

and install this github actions workflow

```
name: release

on:
  push:

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: install node
      uses: actions/setup-node@v1
      with:
        node-version: 14.x
    - name: Cache node dependencies
      uses: actions/cache@v2
      env:
        cache-name: cache-dependencies
      with:
        path: |
          ~/.npm
        key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('package-lock.json') }}
    - name: install node dependencies
      run: npm install
    - name: build
      run: npm run build
    - name: release
      run: npm run release
      env:
        GITHUB_TOKEN: ${{ github.token }}
```

You can now release new versions by issuing `npm version <major|minor|patch>`.

# Allowing your user to send debug information

In your plugin, add `import { DebugLog } from 'zotero-plugin/debug-log'` to your startup file, then
after `Zotero.Schema.updateSchemaPromise` clears, call

```
DebugLog.register('your plugin name', ['extensions.zotero.<your plugin extension root>.'])
```

the array is a list of either full names of preferences you want to know about, or a name ending in `.` which means "all keys directly under this".

The Help menu will now have an entry "send debug log to file.io"; when your user selects that, the error log and the selected settings will be sent to file.io; if any items are selected, when that is clicked, a copy of those items will be included in RDF format.

The user will get an ID that looks like `C3WvhYgA8RDM-2XZGASLV`; the first part is the file.io ID, so you would go to `https://file.io/C3WvhYgA8RDM` to retrieve the download; the zipfile you get there will be `2XZGASLV.zip`.

# Starting Zotero with your plugin loaded

Note it is *much* adviced to create a separate Zotero profile for testing!

You will need to have python3 installed to use this.

Create a file called `zotero-plugin.ini` with the following contents:

```
[profile]
name = <your test profile name> # optional. when not present, the profile picker will popup, where you can select the test profile
path = <your test profile absolute path>

[zotero]
path = <explicit path to zotero binary> # optional
log = <file name to write log output to> # optional
db = <path to zotero.sqlite you want to populate the profile with> # optional

[plugin]
source = <plugin source directory> # optional
build = <command to build your plugin, or false if no build is needed> # optional

[preferences]
extensions.zotero.<your extension>.<some setting> = <value>
extensions.zotero.<your extension>.<some other setting> = <value>
```

and add this script to your package.json:

```
  "start": "zotero-start"
```

then when you execute `npm start`, zotero will start up with the latest build of your plugin installed, and the given preferences set.

**DO CREATE A BACKUP OF YOUR ZOTERO DATA *AND* YOUR ZOTERO PROFILE BEFORE USING THIS THE FIRST TIME**

`zotero-start` will **blindly** trust you've set it up right and will **alter data** in the profile