Document ts project references setup #78586

mshustov · 2020-09-28T13:38:24Z

part of #46773
adds docs for the solution teams to migrate plugins to TS project references

mshustov · 2020-09-28T13:43:27Z

docs/development/typescript.md

+2. Your plugin exports something inferring a type from a 3rd party library that doesn't export this type. To fix the problem, you have to declare the exported type manually.
+
+### Prerequisitions
+Since `tsc` doesn't support circular references, the migration order does matter. You can migrate your plugin only when all the plugin dependencies already have migrated. It creates the situation when low-level plugins (such as `data` or `kibana_react`) have to migrate first.


It would be useful to add a script showing a plugin dependency tree. I didn't manage to find an issue - I can create one. Should we prioritize it? Manual migration order tracking is not cool.

Could probably be solved by the same tool as #78162 ?

Yes, it would help to understand all the existing deps between plugins. But:

It's no clear when Create tool to identify and visualize circular imports between plugins #78162 is taken in work by the @elastic/kibana-operations

A simple script visualizing a plugin tree from the plugin discovery would do the trick as well. As a bonus, we could highlight all the projects already migrated to TS project refs.

The main problem is the plugin discovery is tightly coupled with the platform runtime. We might have to either extract it in or borrow @kbn/optimizer implementation

kibana/packages/kbn-optimizer/src/optimizer/optimizer_config.ts

Line 213 in 7c6a40e

const plugins = findKibanaPlatformPlugins(options.pluginScanDirs, options.pluginPaths);

joshdover · 2020-09-28T22:59:20Z

ack: will review tomorrow

docs/development/typescript.md

joshdover · 2020-09-29T19:33:05Z

docs/development/typescript.md

+2. Your plugin exports something inferring a type from a 3rd party library that doesn't export this type. To fix the problem, you have to declare the exported type manually.
+
+### Prerequisitions
+Since `tsc` doesn't support circular references, the migration order does matter. You can migrate your plugin only when all the plugin dependencies already have migrated. It creates the situation when low-level plugins (such as `data` or `kibana_react`) have to migrate first.


Could probably be solved by the same tool as #78162 ?

docs/development/typescript.md

joshdover · 2020-09-29T19:35:54Z

docs/development/typescript.md

+```
+If your plugin imports a file not listed in `include`, the build will fail with the next message `File ‘…’ is not listed within the file list of project …’. Projects must list all files or use an 'include' pattern.`
+- build you plugin `./node_modules/.bin/tsc -b src/plugins/my_plugin`. Fix errors if `tsc` cannot generate type declarations for your project.
+- make sure the `target/types` folder doesn’t contain files not belonging to your project. Otherwise, it means your plugin includes files from another project by mistake.


Is there an easy way to detect this?

We can write a script to make sure all files in outDir covered by patterns in includes. However, if code from another plugin is compiled, it means that this plugin has been listed in include. I'm leaning towards removing this note from the doc. WDYT?

If it's not expected to be a common situation, then let's either remove it or move it to a "troubleshooting" section.

Co-authored-by: Josh Dover <me@joshdover.com>

…docuement-ts-project-refa

rudolf

I think these instructions could benefit from a fully worked out example since there's quite a lot of places to edit. Alternatively we could link to the PR that moved kibana_react (but it has some other changes that wouldn't be necessary) or maybe we can link to the PR of the first team that moved their plugin.

rudolf · 2020-10-05T11:04:44Z

docs/development/typescript.md

+Since `tsc` doesn't support circular project references, the migration order does matter. You can migrate your plugin only when all the plugin dependencies already have migrated. It creates a situation where commonly used plugins (such as `data` or `kibana_react`) have to migrate first.
+
+### Implementation
+- make sure all the plugins listed as dependencies in `kibana.json` file have migrated to TS project references.


nit: I think a numbered list makes more sense here since you will generally start at the top and work down

I had to revert it in 6efc968 to the unordered list. asciidoctor fails validation with

18:06:10 INFO:build_docs:asciidoctor: WARNING: developer/best-practices/typescript.asciidoc: line 35: list item index: expected 2, got 1 18:06:10 INFO:build_docs:asciidoctor: WARNING: developer/best-practices/typescript.asciidoc: line 59: list item index: expected 2, got 1 18:06:10 INFO:build_docs:asciidoctor: WARNING: developer/best-practices/typescript.asciidoc: line 60: list item index: expected 3, got 1 18:06:10 INFO:build_docs:asciidoctor: WARNING: developer/best-practices/typescript.asciidoc: line 61: list item index: expected 4, got 1 18:06:10 INFO:build_docs:asciidoctor: WARNING: developer/best-practices/typescript.asciidoc: line 62: list item index: expected 5, got 1

I tried 1., 2., etc. style as well, but the numeration started from 1 after source block. 😞

docs/development/typescript.md

mshustov · 2020-10-05T12:41:16Z

@rudolf added #79446 as an example
@stacey-gammon Should I merge the current file with https://github.com/elastic/kibana/blob/master/TYPESCRIPT.md ? What is a better place for the docs? docs/developer as per #41833 (comment) ?

rudolf

@rudolf added #79446 as an example

Awesome!

stacey-gammon · 2020-10-05T13:00:07Z

@restrry, good question. Merging with https://github.com/elastic/kibana/blob/master/TYPESCRIPT.md looks like a good idea. I'd migrate them both to asciidoc, put inside docs/developer/best_practices, and link to from docs/developer/best_practices/index.asciidoc.

mshustov · 2020-10-05T14:28:33Z

@stacey-gammon converted newly added file. see docs/developer/best-practices/typescript.asciidoc

@rudolf

* document ts project references * Apply suggestions from code review Co-authored-by: Josh Dover <me@joshdover.com> * capitalize all the bullet points * address @rudolf comments * add a reference to example * fix identation * convert into asciidoc * fix numeration * fix asciidoctor failures * cleanup typescript.asciidoc * back to unordered list. asciidoctor fails validation Co-authored-by: Josh Dover <me@joshdover.com>

* master: (85 commits) Refactor attribute service (elastic#78414) [APM] Add default message to alerts. (elastic#78930) [Discover] Modify columns and sort when switching index pattern (elastic#74336) Document ts project references setup (elastic#78586) build all ts refs in single kbn:bootstrap (elastic#79438) [TSVB] Allow string fields on value count aggregation (elastic#79267) [SECURITY SOLUTION] Investigate EQL signal in timeline (elastic#79049) [Fleet] Add loading spinner to page headers (elastic#79568) [Security Solution][Resolver] Resolver query panel load more (elastic#79160) Add type row to monitor detail page. (elastic#79556) Remove license refresh from setup (elastic#79518) [docker] add reporting fonts (elastic#74806) [SECURITY_SOLUTION][ENDPOINT] Add info about trusted apps to the page subtitle + create flyout (elastic#79558) Trim Hash value before validating it (elastic#79545) Warn users when security is not configured (elastic#78545) update copy styling (elastic#79313) Update dependency @elastic/charts to v23.1.1 (elastic#78459) Introduce geo-threshold alerts (elastic#76285) elastic#76920 Show base breadcrumb when there is an error booting the app (elastic#79571) remove react-intl from kibana and keep it inside only i18n package (elastic#78956) ...

@rudolf

* document ts project references * Apply suggestions from code review Co-authored-by: Josh Dover <me@joshdover.com> * capitalize all the bullet points * address @rudolf comments * add a reference to example * fix identation * convert into asciidoc * fix numeration * fix asciidoctor failures * cleanup typescript.asciidoc * back to unordered list. asciidoctor fails validation Co-authored-by: Josh Dover <me@joshdover.com> Co-authored-by: Josh Dover <me@joshdover.com>

document ts project references

6eac83d

mshustov added chore v8.0.0 release_note:skip Skip the PR/issue when compiling release notes v7.10.0 docs labels Sep 28, 2020

mshustov commented Sep 28, 2020

View reviewed changes

mshustov changed the title ~~Document ts project references~~ Document ts project references setup Sep 28, 2020

mshustov mentioned this pull request Sep 28, 2020

Switch to typescript project references and incremental builds #46773

Closed

7 tasks

mshustov requested a review from a team September 28, 2020 13:45

joshdover reviewed Sep 29, 2020

View reviewed changes

mshustov and others added 3 commits September 30, 2020 09:27

Apply suggestions from code review

dc5a6a7

Co-authored-by: Josh Dover <me@joshdover.com>

Merge remote-tracking branch 'origin/docuement-ts-project-refa' into …

90062e1

…docuement-ts-project-refa

capitalize all the bullet points

aeec0f3

mshustov requested review from joshdover and a team September 30, 2020 18:09

joshdover mentioned this pull request Oct 2, 2020

Create tool to identify plugin import dependencies to support TS project references migration #79343

Closed

rudolf reviewed Oct 5, 2020

View reviewed changes

mshustov added 3 commits October 5, 2020 14:51

address @rudolf comments

910cd09

add a reference to example

225ec42

fix identation

da5d86e

mshustov requested a review from rudolf October 5, 2020 12:42

rudolf approved these changes Oct 5, 2020

View reviewed changes

mshustov added 2 commits October 5, 2020 16:53

Merge branch 'master' into docuement-ts-project-refa

cc2ba37

convert into asciidoc

e786249

fix numeration

aa38635

mshustov added 3 commits October 5, 2020 17:59

fix asciidoctor failures

536b099

cleanup typescript.asciidoc

abbe6eb

back to unordered list. asciidoctor fails validation

6efc968

mshustov merged commit 6f98372 into elastic:master Oct 6, 2020

mshustov deleted the docuement-ts-project-refa branch October 6, 2020 06:47

mshustov mentioned this pull request Oct 6, 2020

[7.x] Document ts project references setup (#78586) #79615

Merged

mshustov added the backported label Oct 6, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document ts project references setup #78586

Document ts project references setup #78586

mshustov commented Sep 28, 2020 •

edited

Loading

mshustov Sep 28, 2020 •

edited

Loading

joshdover Sep 29, 2020

mshustov Sep 30, 2020

joshdover commented Sep 28, 2020

joshdover Sep 29, 2020

joshdover Sep 29, 2020

mshustov Sep 30, 2020

joshdover Oct 2, 2020

rudolf left a comment

rudolf Oct 5, 2020

mshustov Oct 5, 2020

mshustov commented Oct 5, 2020

rudolf left a comment

stacey-gammon commented Oct 5, 2020

mshustov commented Oct 5, 2020 •

edited

Loading

Document ts project references setup #78586

Document ts project references setup #78586

Conversation

mshustov commented Sep 28, 2020 • edited Loading

mshustov Sep 28, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshdover commented Sep 28, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rudolf left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mshustov commented Oct 5, 2020

rudolf left a comment

Choose a reason for hiding this comment

stacey-gammon commented Oct 5, 2020

mshustov commented Oct 5, 2020 • edited Loading

mshustov commented Sep 28, 2020 •

edited

Loading

mshustov Sep 28, 2020 •

edited

Loading

mshustov commented Oct 5, 2020 •

edited

Loading