CONTRIBUTING.md

Contributing

Reporting bugs

Report any bugs in the GitHub Issue Tracker.

Please follow the issue template as closely as possible:

• Attach your tsconfig.json, package.json (for versions of dependencies), rollup.config.js, and any other pieces of your environment that could influence module resolution, ambient types, and TS compilation.

Some additional debugging steps you can take to help diagnose the issue:

• Attach plugin output with verbosity option set to 3 (this will list all files being transpiled and their imports).
• If it makes sense, check if running tsc directly produces similar results.
• Check if you get the same problem with clean option set to true (might indicate a bug in the cache).
• Check if the problem is reproducible after running npm prune to clear any rogue types from node_modules (by default TS grabs all ambient types).

Developing

Use the standard GitHub process of forking, making a branch, creating a PR when ready, and fixing any failing checks on the PR.

Linting and Style

1. Use an editor that supports editorconfig, or match the settings from .editorconfig manually.
2. Fix all linting problems with npm run lint.

Testing

1. npm test to verify that all tests pass
2. npm run test:watch to run tests in watch mode while developing
3. npm run test:coverage to run tests and output a test coverage report

While this repo now has an assortment of unit tests and integration tests, it still needs more integration tests with various scenarios and expected outcomes.

Building and Self-Build

One can test changes by doing a self-build; the plugin is part of its own build system.

1. make changes
2. run npm run build (uses last released version on npm)
3. check that you get expected changes in dist
4. run npm run build-self (uses fresh local build)
5. check dist for the expected changes
6. run npm run build-self again to make sure plugin built by new version can still build itself

If build-self breaks at some point, fix the problem and restart from the build step (a known good copy).

Learning the codebase

If you're looking to learn more about the codebase, either to contribute or just to educate yourself, this section contains an outline as well as tips and useful resources.
These docs have been written by contributors who have gone through the process of learning the codebase themselves!

General Overview

Before starting, make sure you're familiar with the README in its entirety, as it describes this plugin's options that make up its API surface.
It can also be useful to review some issues and have a "goal" in mind (especially if you're looking to contribute), so that you can focus on understanding how a certain part of the codebase works.

1. Can read get-options-overrides as a quick intro to the codebase that dives a bit deeper into the compilerOptions that this plugin forces.
   • The TSConfig Reference can be a helpful resource to understand these options.
2. Get a quick read-through of index (which is actually relatively small), to get a general understanding of this plugin's workflow.
   • Rollup's Plugin docs are very helpful to reference as you're going through, especially if you're not familiar with the Rollup Plugin API.

Deeper Dive

Once you have some understanding of the codebase's main workflow, you can start to dive deeper into pieces that require more domain knowledge.
A useful resource as you dive deeper are the unit tests. They're good to look through as you dig into a module to understand how it's used.

1. From here, you can start to read more of the modules that integrate with the TypeScript API, such as host and parse-tsconfig, and maybe how TS is imported in tsproxy and tslib
   • A very useful reference here is the TypeScript Wiki, which has two main articles that are the basis for most Compiler integrations:
     • Using the Compiler API
     • Using the Language Service API
     • NOTE: These are fairly short and unfortunately leave a lot to be desired... especially when you consider that this plugin is actually one of the simpler integrations out there.
2. At this point, you may be ready to read the more complicated bits of index in detail and see how it interacts with the other modules.
   • The integration tests could be useful to review at this point as well.
3. Once you're pretty familiar with index, you can dive into some of the cache code in tscache and rollingcache.
4. And finally, you can see some of the Rollup logging nuances in context and then the TS logging nuances in diagnostics, and diagnostics-format-host
   • While these are necessary to the implementation, they are fairly ancillary to understanding and working with the codebase.