GA/1.0 release

[jawj]

This repo began as an experimental project, and that's still evident in the way it's structured. In order to feel confident to release a 1.0 driver version, the following steps are needed (thanks to @amitdahan):

CI: tests

• It makes sense to do this first, so that other refactoring benefits from immediate sanity checks.
• Much of what's in src/index.ts will be a good start, but return values (and ideally also TypeScript types) will need checking.
• We will want to automate testing both WebSockets (Client, Pool) and HTTP (neon) queries.
• We will need to include tests for a range of platforms, since they all offer slightly different capabilities, and some of them take approaches to bundling that can break in a variety of different ways.
• Tested platforms may include:
  • Local/CLI: Node, Deno, Bun
  • Local/web browser (bundling using esbuild and/or others): Chrome, Safari, Firefox.
  • Serverless (remote and/or local dev): Cloudflare Workers, AWS Lambda, Vercel (Edge) Functions (both 'raw' and using Next.js)

CI: formatting/linting

• Consistent code formatting. The code should largely already be formatted according to VS Code defaults and what's in .vscode/settings.json.

CI: PR previews

• Enable PRs to be installed as packages. This could be especially useful when testing changes on serverless platforms such as Cloudflare, which is otherwise very tricky.

Repo structure

• The code in src/index.ts exercises the driver but is not part of the driver. The npm package is in dist/npm with its own, separate package.json. Much of the source is in shims (especially shims/net/index.ts), but this is surprisingly not under src.
• This is unusual and not very logical, and we should aim to refactor/restructure it in a way that helps us and any external contributors.

Other

• We could use a separate release branch instead of main.
• We could consider changesets, though these "are designed first and foremost to handle versioning in multi-package repos", which this is not.

[duskpoet]

For changesets conventional commits work nicely for me in neonctl repo

[duskpoet]

And automated release routine

[amitdahan]

For changesets conventional commits work nicely for me in neonctl repo

You mean semantic-release (which relies on conventional commits), right?

[amitdahan]

though these "are designed first and foremost to handle versioning in multi-package repos", which this is not.

I've seen changesets being used nicely in non-multi-package packages just fine, personally I liked the separation between changelog and the PR/commit title.

Can be seen here:
Schniz/fnm#760 (or more up-to-date here)

---

But anyway, we can consider any.

[amitdahan]

On the topic of "Repo structure":

Wdyt of making all "build output" gitignored? So dist/* etc.

CI can always just build before publishing, or testing.

And locally we can have convenience scripts and instructions in DEVELOP.md/CONTRIBUTING.md (and optionally use turbo to automate running dependent scripts)

[pffigueiredo]

Some things to add to the list:

• improve local development experience by setting up an example and allowing testing with the new code
• automated types
• a better "contributing.md" guide
• standardize formatting/linting in the repo
• setup renovate to make sure our packages are up to date
• setup a better publishing experience with something like https://github.com/release-it/release-it, there are a lot others