From b8410af988dea74d79c2583272869931030ddb51 Mon Sep 17 00:00:00 2001 From: Anton Gilgur Date: Sun, 1 May 2022 11:59:46 -0400 Subject: [PATCH 1/2] docs: split off a CONTRIBUTING.md from the README - condenses the README a bit and uses the standard CONTRIBUTING.md file - it's a file I often look for when filing an issue or creating a PR - leaves the section still in the README so that users (esp. on NPM) will know to go there if they're not aware of that convention - GitHub also now tells users to read the CONTRIBUTING.md of a repo when filing issues or creating PRs, so hopefully this helps point more users in the right direction as well --- CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++ README.md | 30 ++---------------------------- 2 files changed, 33 insertions(+), 28 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b85c71e4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# Contributing + +## Reporting bugs + +Report any bugs on github: . + +Attach your `tsconfig.json`, `package.json` (for versions of dependencies), rollup script and anything else that could influence module resolution, ambient types and typescript compilation. + +Check if problem is reproducible after running `npm prune` to clear any rogue types from npm_modules (by default typescript grabs all ambient types). + +Check if you get the same problem with `clean` option set to true (might indicate a bug in the cache). + +If makes sense, check if running `tsc` directly produces similar results. + +Attach plugin output with `verbosity` option set to 3 (this will list all files being transpiled and their imports). + +## Developing + +Use the normal github process of forking, making a branch and creating a PR when ready. Fix all linting problems (run `npm lint`), fix any failed checks that are run on the PR (basically lint right now). Use an editor that supports editorconfig, or match the settings from `.editorconfig` file manually. + +Fastest way to test changes is to do a self build, the plugin is part of its own build system: +- make changes +- run `npm build` (uses last released version on npm) +- check that you get expected changes in `dist` +- run `npm build-self` (uses fresh local build) +- check `dist` for the expected changes +- run `npm 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 `build` step (a known good copy). + +This repo badly needs unittests and integration tests with various scenarios and expected outcomes though. diff --git a/README.md b/README.md index b4f1f0e5..0446dfc2 100644 --- a/README.md +++ b/README.md @@ -213,32 +213,6 @@ TypeScript `2.4+` Rollup `1.26.3+` Node `6.4.0+` (basic es6 support) -### Reporting bugs +### Reporting bugs and Contributing -Report any bugs on github: . - -Attach your `tsconfig.json`, `package.json` (for versions of dependencies), rollup script and anything else that could influence module resolution, ambient types and typescript compilation. - -Check if problem is reproducible after running `npm prune` to clear any rogue types from npm_modules (by default typescript grabs all ambient types). - -Check if you get the same problem with `clean` option set to true (might indicate a bug in the cache). - -If makes sense, check if running `tsc` directly produces similar results. - -Attach plugin output with `verbosity` option set to 3 (this will list all files being transpiled and their imports). - -### Contributing - -Use the normal github process of forking, making a branch and creating a PR when ready. Fix all linting problems (run `npm lint`), fix any failed checks that are run on the PR (basically lint right now). Use an editor that supports editorconfig, or match the settings from `.editorconfig` file manually. - -Fastest way to test changes is to do a self build, the plugin is part of its own build system: -- make changes -- run `npm build` (uses last released version on npm) -- check that you get expected changes in `dist` -- run `npm build-self` (uses fresh local build) -- check `dist` for the expected changes -- run `npm 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 `build` step (a known good copy). - -This repo badly needs unittests and integration tests with various scenarios and expected outcomes though. +See [CONTRIBUTING.md](./CONTRIBUTING.md) From d92133db10f9cd63778dd65ab6b1eb04ebca25e1 Mon Sep 17 00:00:00 2001 From: Anton Gilgur Date: Sun, 1 May 2022 12:09:53 -0400 Subject: [PATCH 2/2] docs: improve formatting, grammar, and links in CONTRIBUTING.md - slightly change reference to GH Issue Tracker - use oxford commas everywhere for clarity - missing "the" in a few places - more minor grammatical fixes (missing space, semicolon vs. comma, etc) - fix: "npm_modules" -> "`node_modules`" - fix: "npm lint" -> "npm run lint", "npm build" -> "npm run build", "npm build-self" -> "npm run build-self" - short-hand works in Yarn and for some pre-defined Node scripts, like `start` and `test`, but the rest need `run` - "typescript" -> "TS" (prefer proper "TypeScript" or just "TS") - use backticks monospace/code formatting where appropriate - link to GitHub's official docs on forking and making PRs - also use the word "standard" instead of "normal" as it's more inclusive and reflective that this is a convention/standard - link to editorconfig site - link directly to `.editorconfig` with a relative link as well - reword portion about PR checks as they do run `build` and `build-self` nowadays (not sure how old this text is) - use an ordered list (instead of unordered) for the testing process as this is meant to be done in order --- CONTRIBUTING.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b85c71e4..6e9a66af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,30 +2,31 @@ ## Reporting bugs -Report any bugs on github: . +Report any bugs [in the GitHub Issue Tracker](https://github.com/ezolenko/rollup-plugin-typescript2/issues). -Attach your `tsconfig.json`, `package.json` (for versions of dependencies), rollup script and anything else that could influence module resolution, ambient types and typescript compilation. +Attach your `tsconfig.json`, `package.json` (for versions of dependencies), `rollup.config.js`, and anything else that could influence module resolution, ambient types, and TS compilation. -Check if problem is reproducible after running `npm prune` to clear any rogue types from npm_modules (by default typescript grabs all ambient types). +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). -Check if you get the same problem with `clean` option set to true (might indicate a bug in the cache). +Check if you get the same problem with `clean` option set to `true` (might indicate a bug in the cache). -If makes sense, check if running `tsc` directly produces similar results. +If it makes sense, check if running `tsc` directly produces similar results. Attach plugin output with `verbosity` option set to 3 (this will list all files being transpiled and their imports). ## Developing -Use the normal github process of forking, making a branch and creating a PR when ready. Fix all linting problems (run `npm lint`), fix any failed checks that are run on the PR (basically lint right now). Use an editor that supports editorconfig, or match the settings from `.editorconfig` file manually. +Use the [standard GitHub process](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model) of forking, making a branch, and creating a PR when ready. Fix all linting problems (`npm run lint`) and fix any failed checks on the PR. Use an editor that supports [`editorconfig`](https://editorconfig.org/), or match the settings from [`.editorconfig`](./.editorconfig) manually. -Fastest way to test changes is to do a self build, the plugin is part of its own build system: -- make changes -- run `npm build` (uses last released version on npm) -- check that you get expected changes in `dist` -- run `npm build-self` (uses fresh local build) -- check `dist` for the expected changes -- run `npm build-self` _again_ to make sure plugin built by new version can still build itself +Fastest way to test changes is to do a self build; the plugin is part of its own build system: -If `build-self` breaks at some point, fix the problem and restart from `build` step (a known good copy). +1. make changes +1. run `npm run build` (uses last released version on npm) +1. check that you get expected changes in `dist` +1. run `npm run build-self` (uses fresh local build) +1. check `dist` for the expected changes +1. run `npm run build-self` _again_ to make sure plugin built by new version can still build itself -This repo badly needs unittests and integration tests with various scenarios and expected outcomes though. +If `build-self` breaks at some point, fix the problem and restart from the `build` step (a known good copy). + +This repo badly needs unit tests and integration tests with various scenarios and expected outcomes though.