fix(github): improve formatting of issue template spoilers

[agilgur5]

Summary

Improve formatting of the issue template with code blocks and fixing some duplication

Details

• I originally added the spoilers in github: add spoiler tags to issue template #244 and while they work (and I would say improve readability a good bit), there's also some issues with them

  • I've used them a ton more now so know how to workaround most of the issues with them now

• fix: use HTML code tag inside of summary tag, can't use backticks

  • was mixing MD and HTML before, and this doesn't always work and didn't work on GitHub, they just had visible backticks before

• fix: don't duplicate the file name in the heading, just make the summary have a heading inside it instead

  • use an h4 same as the #### that it was before

• feat: add syntax highlighting by adding code blocks for each code snippet

  • js for rollup.config.js, json5 for tsconfig (it has comments, trailing commas, etc (actually a custom parser, but json5 is close enough)), json for package.json, and text for verbose logs
  • also, a lot of people sometimes just paste the code with no code block and it formats terribly, so this should help defer that (as well as any potential issues that can crop up with unindented blocks)
    • the envinfo text code block that I added in github: use envinfo for getting versions in issue reports #245 seems to be working well and used in most issues, so hopefully this will improve issues too

References

I wrote #310 using this format as an example! Think it's a good bit cleaner

• As for examples of how it previously looked and why this is better, Type '{}' is not assignable to type 'ReactNode' with Bitbucket pipelines cache (works locally) -- need to specify @types/react-dom #309 shows an example with no syntax highlighting but use of code blocks, whereas semantic error TS2339: Property 'write' does not exist on type 'Clipboard' -- can't repro #306 uses no code blocks at all and so isn't formatted well and GitHub/Markdown doesn't indent it either. Both are properly using spoilers as well.

[ezolenko]

Looks good, thanks

[agilgur5]

@ezolenko unrelated, but would you want to give me "Triage" access to this repo? I occasionally go through the issues myself and respond myself, and figure as an experienced maintainer I can triage/format/edit/label/organize/etc a bunch of things as well as close out issues that I think are stale or have been resolved. Ones that I'm not sure of I'd leave to you of course -- we can work out what the specifics of that would look like as well.

Not that I have a ton of time myself, but I figure two is better than one any day, and I'm an occasional contributor anyway already. And I know from my own experience and from this repo's issues too that a lot of time is spent on issues.

Can see TSDX's labels for an example of what's probably the most organized repo I've maintained.

[ezolenko]

@agilgur5 Sure! Invite sent. I have almost no time for this repo, just enough to check incoming PRs and such, so any help is welcome

[agilgur5]

Thanks @ezolenko !

I have almost no time for this repo, just enough to check incoming PRs and such, so any help is welcome

That makes sense. This plugin started as a simple fork and evolved to be the most popular TS plugin by a long margin so 😅
It still works for 80% of use-cases too, and all of the TS plugins unfortunately have their own issues -- kind of wish there was an official one maintained by the TS team 😕

maintenance done so far

You've probably seen some of my work already if you have notifications turned on, but here's a quick summary/heads-up for your information:

1. Added something like ~40 labels based on my past experience plus some specific ones for this repo. May add more specific ones moving forward as I see more patterns.
   • Changed the naming of existing labels to fit the label categories I use (kind, scope, problem, solution, topic)
   • Made this fork of github-label-manager to help with adding all the labels too.
   • Standardized some label colors that I haven't done in all my repos yet (always a WIP)
2. Labeled and re-formatted 100+ open and closed issues
   • You'll see the labels everywhere now
   • You'll see edited by agilgur5 in dozens of comments in all sorts of places where I reformatted for syntax highlighting, spoiler tags (like those here), added back-links, etc
3. Closed out around ~30 issues that were duplicative, stale, already responded to, etc.
4. Locked ~20+ long resolved issues so that they don't get necro'd
   • Happens pretty often that an someone comments on a closed issue without a repro and things have changed so much in the timeframe, so it's much better to open a new issue. Have started locking many closed issues in most of my repos as such.
   • Many more to lock remaining!
5. Responded to many more issues (~50?) either with closure notice, duplication notice, or with workarounds, possible resolutions, or confirmations of issues.

I've gone through most of the open issues now and about 2-3 pages of closed issues as well (good for context, history, and patterns. as well as self-closed issues) -- will get to organizing the rest eventually.

I think that's pretty good progress in a week! 🙂 Let me know if you have any constructive feedback -- can converse over email for privacy too.

patterns in the issues to improve on

Some patterns I've noticed so far:

1. Many issues are ones where tsc would have similar behavior, so they are not bugs. See solution: tsc behavior label
2. Some are plugin order misconfigurations. See problem: plugin order label
   • Planning to solve 1. and 2. with modifications to the issue template. I'll likely be iterating on that a bit, so stay tuned for PRs there as well as to a CONTRIBUTING.md
     • EDIT: see docs: split off a CONTRIBUTING.md and improve formatting, grammar, links #313 for CONTRIBUTING.md
     • EDIT2: issue template improvements are WIP; have actually had an unfinished branch for that open for a while, was waiting to get the CONTRIBUTING.md and testing out first
       • EDIT3: see github: add troubleshooting steps to the issue template #350 for main issue template improvements
3. Many are missing reproductions or can't be easily reproduced.
   • Have actually been long planning (since at least skipLibCheck: false does not output diagnostics for ambient types #212 when I was a contributor) to add a simple Codesandbox or Stackblitz minimal environment for use in the issue template and for quick reproductions without installing a whole repo locally.
     • EDIT: this is WIP. currently thinking of forking off https://repl.it/@rollup/rollup-plugin-repro that the @rollup/plugins monorepo uses (I also played around with StackBlitz for one of my other OSS projects today, but repl.it has a significant portion of its codebase open-sourced (unlike StackBlitz), so I'm leaning in its direction)
     • EDIT2: ended up making a StackBlitz repro env in github: add a reproduction environment to the issue template #354 (can also see reasoning there behind the decision)
4. Some are incorrectly using this plugin's options
   • See Add schema checking for plugin options #312 for my plan to resolve that
5. Handful of cache issues resolved by clean: true. See scope: cache label
   • EDIT: these have all been fixed now (or are in progress by contributors), can see PRs under the same label
6. Some monorepo / symlink issues. See topic: monorepo / symlinks label
   • Either some realpathing is needed or these are more user-land issues that this plugin can't necessarily fix, i.e. things outside of the source directory or tsconfig include etc. Possibly a bit of both.
   • EDIT: fixed in fix: add realpath to host to properly resolve monorepos / symlinks #332
7. Type-only imports have been a long-standing, recurring source of issues.
   • I investigated more in type-checking doesn't work on type-only modules #298 (comment) and would really like to solve this
     • EDIT: I've completed a root cause analysis in type-checking doesn't work on type-only modules #298 (comment) . Think I can get a fix out soon, although it's non-trivial and may need significant testing -- i.e. may want to add an integration test suite first before releasing that fix (may work on those in parallel though).
     • EDIT2: Have a partial fix out in fix: type-check included files missed by transform (type-only files) #345
     • EDIT3: This is fully fixed by fix: handle all type-only imports by piping TS imports #406 !!!
8. A number of head-scratching issues where tsc acts different from this plugin. May be solved by some of the above.
   • EDIT: at least some are indeed solved by fixing the symlink issues, i.e. fix: add realpath to host to properly resolve monorepos / symlinks #332
   • EDIT2: I actually couldn't reproduce most of the others, see github: add a reproduction environment to the issue template #354 for a small list

Already have a few PRs in the works for some of these and some small refactors for simplification, so hopefully those add to stability / usability / DX in the long-run.

[agilgur5]

maintenance update

As of last week, I have officially gone through nearly 100% of all issues, open and closed, 250+ in total, as well as various PRs.

Other notable things:

• Released fixes to monorepos / symlinks in fix: add realpath to host to properly resolve monorepos / symlinks #332, which are the 2nd most common issue in rpt2, after type-only imports
• Did several root cause analyses on monorepos / symlinks and type-only imports (i.e. the two most common issues)
• Created the whole unit testing suite and got it to 100% coverage in the files it tests in test: add initial unit test suite #321
  • CI now runs a matrix on multiple OSes and LTS Node versions to ensure compatibility
  • Integration testing is WIP
    • EDIT: See the beginnings of integration testing in test: add initial integration test suite #371 ! 🙂
• Refactored a decent bit of code for it to be simpler, use less deps, or be more readable
• Have also been contributing to improving the release notes, CONTRIBUTING.md, etc.

1. Added a handful more labels specific to rpt2
2. Labeled and reformatted 100% of all open and closed issues.
   • A handful or so I haven't fully investigated or fixed, either because the complexity was high, or no repro was provided, etc. These can often be identified by their lack of labels (e.g. only one label) or lack of locking etc.
   • It was actually pretty insightful to look through old issues and get the history and context of this repo. In particular, some of the very early issues gave me a better understanding of certain historical design decisions and how certain features came to be.
3. Closed out another ~20 issues, down to 39 open ones now, many of which are either long-standing issues or have no repros / are stale
   • Many of these were actually fairly complex and so I gave detailed responses or even did root cause analysis for some.
   • The stale / no repro ones I'm hoping to make quick repros of once I create a repro environment (WIP) and then either close out or mark as bug and investigate.
4. Probably locked close to ~200 issues and PRs (maybe only 150? I didn't keep track, but it's the vast majority)

patterns

1. Integration issues with Vue and Svelte are somewhat common (c.f. Rollup error Could not resolve TS files without extension (.ts) from Svelte files #283, Importing Vue SFC from lang="ts" block #129, etc)
2. Misconfigurations of rootDir causing TS to place types in a subdirectory (dist/src) is somewhat common (c.f. Generated types placed in unexpected directory -- need to set rootDir in tsconfig #275, declarationDir outputs extra src folder? -- need to set rootDir in tsconfig #64)
3. Trying to use tsconfig's noEmitOnError and not knowing about the plugin option abortOnError is fairly common (Vague failed to transpile error -- noEmitOnError: true breaks rpt2 #254, can't emit JS on TS syntax error even when noEmitOnError is false -- use plugin option abortOnError #206, noEmitOnError: false seems to be ignored -- use plugin option abortOnError #62, errors only reported for one file at a time -- use abortOnError: false #60, watch mode doesn't bundle when error on first build -- use plugin option abortOnError #31, etc)
   • I'm hoping my recent PR fix: force noEmitOnError: false #338 that added a note at the top of the docs helps abate this.
   • Implementing abortOnError enhancement: get *all* errors, *then* abort #168 may also help obviate users' need to configure this option as well.
4. Downstream misconfiguration or version issues in libraries like microbundle are fairly common. See the new scope: downstream label.
5. Bugs creating warranted confusion around the plugin include/exclude vs the tsconfig include/exclude (exclude filters .js output, but not .d.ts (plugin exclude vs. tsconfig exclude) #225, co-located test types included in dist (tsconfig exclude vs plugin exclude) #280)
   • EDIT: fixed in fix: filter "missed" declarations as well #347

There are some one-off issues that aren't quite patterns but that I think are pretty important to fix, such as:

1. Multi-entry doesn't completely work out-of-the-box per Declaration generated in wrong folder when using object as input (multi-entry) #136
2. ^I think this may also impact code-splitting as well, esp. as I don't believe we'd produce typings for split chunks
3. Getting files to work per Declarations not generated for type-only files not explicitly specified in tsconfig #211 .
   This may be fixed by the type-only imports fix though, as it wouldn't rely on parsedConfig.fileNames/the tsconfig include anymore, and would instead use ts.preProcessFile to create an import chain.

Think that'll be the last update/maintenance summary I'll give since I've gone through all the issues now and these patterns are much smaller now. The few issues leftover don't really need a summary or are already part of previous patterns listed.

[ezolenko]

Awesome job, thanks a lot!