Migrate Pursuit application to the monorepo

Offen
  • Stimmt etwas nicht?
#789 1 Kommentar 1 Reaktion 1 zugewiesene Person Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

@thomashoneyman arbeitet bereits daran.

Seit 27.7.2026.

Bewertung

Dieses Issue wurde noch nicht bewertet.

Beschreibung

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.

Vorherrschende Sprache
PureScript
Sterne
95
Forks
79
Ø Merge
16 Std. 13 Min.
Gemergte PRs (30 T.)
14

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus purescript/registry-dev

Alle Issues in purescript/registry-dev

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.