Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(github): improve formatting of issue template spoilers #311

Conversation

agilgur5
Copy link
Collaborator

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)

References

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

- I originally made the spoilers 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 backticks

- 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 seems to be working well, so
      hopefully this will improve issues too
@ezolenko ezolenko merged commit bfd27a9 into ezolenko:master Apr 21, 2022
@ezolenko
Copy link
Owner

Looks good, thanks

@agilgur5
Copy link
Collaborator Author

agilgur5 commented Apr 21, 2022

@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
Copy link
Owner

@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
Copy link
Collaborator Author

agilgur5 commented May 3, 2022

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
  3. Many are missing reproductions or can't be easily reproduced.
  4. Some are incorrectly using this plugin's options
  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
  7. Type-only imports have been a long-standing, recurring source of issues.
  8. A number of head-scratching issues where tsc acts different from this plugin. May be solved by some of the above.

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 agilgur5 added the scope: github GH-only changes, e.g. issue and PR templates, releases, etc (not docs or CI) label May 7, 2022
@agilgur5 agilgur5 added the kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs label May 26, 2022
@agilgur5
Copy link
Collaborator Author

agilgur5 commented Jun 3, 2022

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
  • 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)
  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)

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
Copy link
Owner

ezolenko commented Jun 6, 2022

Awesome job, thanks a lot!

@agilgur5 agilgur5 deleted the fix-github-improve-formatting-of-issue-template-spoilers branch July 2, 2023 21:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs scope: github GH-only changes, e.g. issue and PR templates, releases, etc (not docs or CI)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants