Migrate Pursuit application to the monorepo

Aperta
  • Qualcosa non va?
#789 1 commento 1 reazione 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@thomashoneyman ci sta già lavorando.

Dal 27/7/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

pursuit

As part of #750 we need to replace the parts of Pursuit which assume packages come from GitHub repositories with SemVer tags. #704 tracks defining and storing a registry-owned docs format, and #525 tracks generating that format without calling purs publish. Once those are in place we still need an application that can actually serve those docs.

I think the new Pursuit should live in this repository rather than in a separate repository. It can be its own PureScript package and executable, separate from the registry server itself, but then we can share types and rendering code directly and use the same Nix and deployment infrastructure. The existing Haskell Pursuit can remain the reference implementation while we build this, but it's not a port, it's a rewrite.

The rough model discussed in #704 is that Pursuit would be mostly static:

  • The canonical docs JSON for each package version lives in a DigitalOcean bucket.
  • We generate package and module HTML from that JSON ahead of time and upload it to the same bucket (or another static origin).
  • A small Pursuit server remains for things which are necessarily dynamic, like search, redirecting to the latest version, listing available versions, and badges.
  • Package source links go to the registry package viewer instead of GitHub.

The package viewer should probably move into this repository too, even if it is still deployed as an independent static application. That gives us one place for all of the code that makes up Pursuit.

We should preserve the public parts of Pursuit that people and package managers depend on. In particular:

  • Existing package and module URLs should continue to work.
  • Declaration fragments should remain stable.
  • Links to dependencies and re-exports should use the exact versions recorded in the docs.
  • The available-versions endpoint and badges should keep working.
  • Old purescript-foo URLs should permanently redirect to proper registry names such as foo, completing the Pursuit side of #388.
  • Existing unversioned URLs should continue redirecting to the latest version.

The registry will be the only publisher to the new Pursuit. We don't need to recreate the existing GitHub-token upload flow because package identity and authorization have already been handled by the registry before the docs artifact is generated.

We will also need to migrate existing documentation. For packages and versions in the registry we should be able to regenerate docs from their stored tarballs. For historical packages which only exist in Pursuit, Nathan's migration code in #704 can convert the contents of pursuit-backups and fetch any missing README files. We should do this progressively and keep track of packages which can't be migrated, rather than making the whole migration all-or-nothing. We still need to decide whether non-registry historical packages should remain visible by default.

During development the registry can continue publishing to the existing Pursuit while also generating docs for the new one. Once we have migrated the existing docs, verified the old URLs, and run the new application in a preview environment, we can move pursuit.purescript.org over. It would be useful to keep the old Pursuit available as a temporary fallback for pages that weren't migrated correctly, with those fallback requests logged so we can repair them.

Search and compiler-versioned Prim documentation are large enough to track in a separate issue, but both are requirements for switching production Pursuit over.

Lingua principale
PureScript
Stelle
95
Fork
79
Merge medio
16h 13m
PR unite (30g)
14

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di purescript/registry-dev

Tutte le issue di purescript/registry-dev

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.