You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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.
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 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:
purescript-fooURLs should permanently redirect to proper registry names such asfoo, completing the Pursuit side of What should we do about purescript- prefixes? #388.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-backupsand 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.orgover. 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
Primdocumentation are large enough to track in a separate issue, but both are requirements for switching production Pursuit over.