Improve contributors and users experience

[wellwelwel]

Based on various contributions (including Discussions, Issues, Pull Requests, and comments — also in private messages asking for help), I would like to improve a few things where I feel the contributors have the most difficulty (or that I notice, even when nothing is said).

These are my ideas:

Contributors

Contributing

• Including a template when opening Issues and Pull Requests.
• In addition to the Contribution Guide, I believe it's really useful to have tips on how to create and modify tests for features and fixes.
• docs: include instructions to LLM agents #4185

Automations

Several issues remain open because they have no way of being reproduced. For some time now, I have categorized them by adding a label to identify them, but it doesn't send a notification to the person who opened the Issue or a "formal request".

• I'd suggest an automation to create a default comment asking for a "basic repro" on Issues that need reproduction after adding this label. It would be of great help and, as it is triggered manually, it wouldn't cause any spam.

Testing

I think that reworking the test flow to be more practical/familiar is a good starting point:

• Unite all tests to /test/esm/ (so, just /test/ — no more mixed tests between CJS/require and ESM/import).
  • chore: support Docker testing locally #4019
  • ci: simplify esm tests #4085
  • ci: transcribe esm tests to TypeScript #4086
  • ci: transcribe cjs tests to ES Modules and TypeScript #4091
  • ci: simplify tests #4092
  • ci: add support for parallel runs #4094
  • chore: remove legacy tests #4102
  • Migrate tsc-build tests
    • ci: remove redundant type tests #4119
    • Create real tests to remaining build tests

Users

Bun and Deno

• It's interesting to include the installation guide for these runtimes too, as well as highlighting some possible differences in use between them (e.g., @types/node conflict for Deno with TypeScript).

Documentation

• Refer to the mysqljs/mysql documentation for sections and features that aren't present in the MySQL2 documentation, suggesting contributions for their inclusion.
  • This also includes opening a dedicated Issue for unimplemented features, if found.
• I also consider that we could include a /llms.txt with instructions in the website on where critical functions are and their use, directing the documentation with an improved NLP for AI users and editors.

[sidorares]

all are really good points. For "contibuting" - would be good to include high level overview of the components and connection between them ( this should also help ai editor users to generate better code )

[jeengbe]

Do you have plans for porting the entire lib/ code base to TypeScript? That was my single one greatest worry writing my PR. The project scope is manageable and I would be happy to help

[wellwelwel]

Do you have plans for porting the entire lib/ code base to TypeScript? That was my single one greatest worry writing my PR. The project scope is manageable and I would be happy to help

Hey, @jeengbe! Please, see #2803 (comment).

Right now, all it takes is a "yes" from @sidorares, but I recommend checking for context and discussing it in the issue I mentioned 🙋🏻‍♂️

[sidorares]

Do you have plans for porting the entire lib/ code base to TypeScript? That was my single one greatest worry writing my PR. The project scope is manageable and I would be happy to help

it's a yes from me. I'd like to discuss first how we want to do that and what are possible implications to DX - various things that might ( or might not ) be an issue

• one big pr vs multiple smaller changes
• package size impact
• sourcemaps?
• CI time impact
• compile target and runtime versions we want to support

[sidorares]

Bun and Deno

maybe worth adding cloudflare as its it's own runtime

[wellwelwel]

maybe worth adding cloudflare as its it's own runtime

Cloudflare Workers has a dedicated documentation on how to use it with MySQL2: https://sidorares.github.io/node-mysql2/docs/documentation/connect-on-cloudflare.

---

package size impact + sourcemaps? + possible implications to DX

The project already exports types today manually with .d.ts files in /typings and this is already reflected if someone tries to inspect the code (talking about sourcemaps).

• It's not as if it were a new implementation for the end user, we would just be consolidating what is already done today manually.

---

CI time impact

The tests already run through Bun or Deno natively with TypeScript and, for Node.js, we use tsx under the hood.

• From: we already test the "improvised" manual compilation
• To: we will compile natively by design

---

compile target and runtime versions we want to support

My idea is to keep exactly the same versions we truly support (Node.js 14), even though package.json indicates Node.js 8. This is not a limitation of TypeScript, but a choice of ours.

---

one big pr vs multiple smaller changes

I thought about this for a long time. Development with TypeScript can be done entirely in parallel in the /src directory while we serve, as always, the original /lib and types as it has always been.

The /src path will never be exposed to npm until the work is considered finished.

• No pressure for fast merges due to merge conflicts
• Contributions continue normally in core (/lib) to not block bug fixes
• We decide when /lib will be replaced by the /src build
• We can enable a single CI workflow until this decision, to ensure compatibility without compromising GitHub Actions time and resources

[wellwelwel]

@sidorares, my biggest critical point is, personally: even if a breaking change is necessary for TypeScript users (since we will inevitably solve many problems caused by manual implementations in .d.ts files), it should be as if nothing happened for those who use JavaScript.

If we want to change something in JavaScript (core), that should have its own scope/semver to ensure the TypeScript transition is completely faithful.

[wellwelwel]

CI time impact

@sidorares, a really brief/simple test just to see in practice the impact on CI time:

• Left: Everything as TypeScript (.ts) (~24s)
• Right: Current approach (core as .js, tests as .ts) (~24s)

---

~1.7s of build time (.ts to .js build), even with 1,213 errors (which is to be expected, since I just abruptly changed all the file extensions to .ts):

• Without errors, naturally, this time will be a little shorter
• Today, it takes ~1.2s to perform the tsc-build check without any errors (without emit any files, only check a minor scope in test/tsc-build and not the entire code)

---

Note

Naturally these tests were simple just to test a concept and were based on my personal computer 🙋🏻‍♂️