Migrate Pursuit application to the monorepo

Aberta
  • Algo errado?
#789 1 comentário 1 reação 1 responsável Ver no GitHub

Mantenedores costumam responder em até 1 dia

@thomashoneyman já está trabalhando nisso.

Desde 27/7/2026.

Avaliação

Esta issue ainda não foi avaliada.

Descrição

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.

Linguagem predominante
PureScript
Estrelas
95
Forks
79
Merge médio
16h 13min
PRs com merge (30d)
14

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de purescript/registry-dev

Todas as issues de purescript/registry-dev

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.