hypothesis / hypothesis/client

Reduce duplication of PDF viewer resources and tools across repositories

Open
#4,397 0 comments 0 reactions 0 assignees View on GitHub
technical debt
Dominant language
Mustache
Stars
730
Forks
224
PR merge metrics
No merged PRs in 30d

Description

Hypothesis currently includes builds of the PDF.js library and viewer application in four separate repositories:

1. [client](https://github.com/hypothesis/client), for use in the dev-server
2. [via](https://github.com/hypothesis/via)
3. [browser-extension](https://github.com/hypothesis/browser-extension)
3. [pdf.js-hypothesis](https://github.com/hypothesis/pdf.js-hypothes.is)

In each of these repositories there are duplicated or near-duplicated resources:

1. An `update-pdfjs` script that fetches the latest version of PDF.js, in the repo's directory for miscellaneous scripts (eg. `tools/`, `scripts/` or `bin/`)
2. A vendored copy of PDF.js and its viewer application with some resources stripped out and minor modifications to the viewer's HTML
3. A `pdfjs-init.js` script that loads Hypothesis into the viewer once the viewer has fully initialized

The process of updating PDF.js involves creating a branch, running the `update-pdfjs` script (or `make update-pdfjs` in the case of Via), testing the changes and creating a PR with the results.

This status quo has some downsides:

1. The process of updating the PDF viewer is different than updating other dependencies, so it is less obvious how to do it
2. Changes to the PDF.s initialization script (pdfjs-init.js) and the tools that update PDF.js (update-pdfjs and the viewer HTML generator) have to be applied separately in each of the repositories, and there is a risk that this doesn't happen
3. There isn't an obvious central place to document things related to how the Hypothesis-augmented PDF.js viewer works
4. The update-pdfjs script currently fetches whatever the latest PDF.js build is from PDF.js' GitHub Pages site, which means that when it is run separately in each of the repos it can end up fetching slightly different versions, if changes are happening upstream

It would be worth looking into ways to reduce this duplication. One possibility is to make [pdf.js-hypothesis](https://github.com/hypothesis/pdf.js-hypothesis) the canonical repo for the Hypothesis-augmented PDF.js viewer and build an npm package from that repo containing a PDF.js build along with the `pdfjs-init.js` script. Other repositories could then consume the npm package as they do for other dependencies. A variation on this would be to create a new repository for a packaged PDF viewer, which is then consumed by all the other repositories.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.