Havana Apollo Plugin

The Havana Apollo Plugin is a JBrowse 2 plugin designed for Apollo 3. It adds Havana-specific annotation controls to Apollo's transcript details and provides a workflow for sending annotated genes to the Havana integration service.

The plugin uses Apollo's change system for annotation edits. Saving to Havana is a separate action that sends selected Apollo gene IDs to the Havana integration API.

Functionality

Gene and transcript biotypes

The plugin provides curated Havana biotype menus for both genes and transcripts.

• Gene biotype selections update the gene's biotype attribute.
• Transcript biotype selections update both the biotype attribute and the Apollo feature type when required.
• Changing a transcript to a non-coding transcript type removes its CDS.
• Changing a transcript to an mRNA creates a CDS spanning the transcript's exon boundaries when a CDS does not already exist.
• All edits are submitted through Apollo's change manager and remain part of the normal Apollo editing history.

Havana annotation attributes

Additional Havana fields are displayed in Apollo's transcript details:

• CDS start and end completeness, stored using the mRNA_start_NF and mRNA_end_NF attributes.
• Controlled remarks for genes and transcripts. These values are selected from the Havana remark menus and are exported to GFF3.
• Hidden remarks for genes and transcripts. These are free-text, multi-value internal notes that are not exported to GFF3.
• Gene symbol editing, which keeps the gene_name and name attributes in sync.
• Gene description editing, stored as a single description value.
• Gene biotype editing alongside the selected transcript's Havana attributes.

The gene section also shows the external gene identifier, Apollo gene identifier, and selected Apollo transcript identifier to make it clear which features are being edited.

Saving annotations to Havana

The fixed Save to Havana button opens a dialog with four workflows:

Selected feature

• Loads the complete top-level gene for the selected transcript.
• Previews the gene and its transcripts, including identifiers, type, biotype, location, strand, remarks, and hidden remarks.
• Warns when the gene already appears to be synchronized with Havana.
• Sends the selected gene to the Havana integration API.

Bulk save

• Finds recent Apollo changes made by the current user.
• Resolves transcript and child-feature changes to their top-level genes.
• Deduplicates the results so each affected gene is shown once, using its most recent change.
• Shows whether each gene is Pending or Done based on its Apollo update and Havana save timestamps.
• Supports one-day, one-week, and one-month date ranges, text filtering, pagination, feature previews, and selection of multiple genes.

Deleted genes

• Finds recent gene deletions made by the current user.
• Deduplicates deleted genes and provides the same date-range, filtering, pagination, preview, and selection controls as bulk save.
• Sends selected genes to the Havana delete workflow together with the current assembly identifier.

Failed saves

• Displays failures reported by the Havana integration service for the current assembly.
• Shows the feature, failure type, error message, submitting user, status, retry count, and creation time.
• Supports date-range filtering, text search, and pagination.

The dialog reports API errors through Apollo notifications. After a successful save that contains changes, the page is refreshed so Apollo displays the latest synchronization state.

Integration flow

1. Havana-specific edits are recorded as standard Apollo changes.
2. The plugin uses the authenticated Apollo internet account token for Apollo and Havana API requests.
3. Apollo supplies top-level feature data and the current user's recent change history.
4. The Havana integration API processes selected save or delete requests and exposes failed-save information.

The plugin therefore requires a configured Apollo API, a reachable Havana integration API, and an authenticated ApolloInternetAccount.

Development

To develop against JBrowse Web and Apollo3:

• Start a development version of JBrowse Web (see here)
• Start a development version of Apollo3
• Install dependencies with pnpm install
• In this project, run pnpm dev
• Add the following to your Apollo3 config:

plugins: [
  {
    name: 'HavanaApolloPlugin',
    url: 'http://localhost:9001/dist/havana-apollo-plugin.umd.development.js',
  },
]

• When you make changes to your plugin, it will automatically be re-built. You can then refresh JBrowse Web to see the changes.

Before submitting a change, run the relevant checks:

pnpm lint
pnpm test
pnpm build

See CONTRIBUTING.md for the contribution, commit, and pull request guidelines.

Publishing to npm

Why versioning depends on Git

pnpm version creates a Git commit and tag for the npm release, so it requires a clean working tree. The tag identifies the source used for that package version.

Run the version command only after committing every change intended for the release:

pnpm version patch

Use minor or major instead of patch when appropriate. The command updates package.json, and the version lifecycle script synchronizes src/version.ts. The current postversion script then pushes the version commit and tag.

Do not update package.json and src/version.ts separately. If another change is committed after the version tag, run the appropriate version command again before publishing so the new release tag includes that change.

Release workflow

1. Complete and commit all release changes on a non-main branch.
2. Run the relevant tests, lint, and build checks.
3. Confirm the working tree is clean with git status --short.
4. Run pnpm version patch, minor, or major.
5. Merge the branch into main through a pull request.
6. Switch to main, pull the merged changes, and run pnpm publish.

pnpm publish is restricted to main or master. If pnpm asks whether to publish from another branch, answer No, merge the pull request, and publish from the updated main branch.

Publish the new version with:

git switch main
git pull --ff-only
pnpm publish

Publishing automatically runs:

• pnpm test and pnpm lint through prepublishOnly.
• pnpm build through prepack.
• pnpm clean through the build's prebuild step.

You do not need to run pnpm clean or pnpm build again immediately before publishing. Run pnpm install only when dependencies changed, the lockfile changed, or node_modules is unavailable.