Merge pull request #101 from DataDog/yoann/add-some-doc

[DX] Improve contribution experience
DataDog · Oct 3, 2024 · 45624e5 · 45624e5
2 parents 8859075 + af4916a
commit 45624e5
Show file tree

Hide file tree

Showing 9 changed files with 548 additions and 60 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -60,9 +60,12 @@ yarn
 We have two types of workspaces:
 
 - `@datadog/*`: The packages we're publishing publically on NPM.
-    - `@datadog/webpack-plugin`: The webpack plugin.
     - `@datadog/eslint-plugin`: The eslint plugin.
+    - `@datadog/rollup-plugin`: The rollup plugin.
+    - `@datadog/vite-plugin`: The vite plugin.
+    - `@datadog/webpack-plugin`: The webpack plugin.
 - `@dd/*`: The packages we're only using internally.
+    - `@dd/assets` | `./packages/assets`: Only the static files used as assets.
     - `@dd/core` | `./packages/core`: The core package that contains the shared code between the plugins.
     - `@dd/factory` | `./packages/factory`: The factory package that contains the logic to aggregate all the plugins together.
     - `@dd/*-plugin` | `./packages/plugins/*`: The plugins workspaces that contains the plugins. Each plugin is a workspace.
@@ -72,6 +75,9 @@ We have two types of workspaces:
 Here's a diagram to help you understand the structure:
 
 ```mermaid
+---
+title: Datadog Build Plugins Design
+---
 stateDiagram-v2
     published: Published Packages
     plugins: Custom Plugins
@@ -81,8 +87,10 @@ stateDiagram-v2
     customplugin12: @dd/*-plugins
     customplugin22: @dd/*-plugins
     customplugin32: [...]
-    webpackplugin: @datadog/webpack-plugin
     esbuildplugin: @datadog/esbuild-plugin
+    viteplugin: @datadog/vite-plugin
+    rollupplugin: @datadog/rollup-plugin
+    webpackplugin: @datadog/webpack-plugin
     tests: @dd/tests
     tools: @dd/tools
     factory: @dd/factory
@@ -93,12 +101,16 @@ stateDiagram-v2
     aplugins: Aggregated List of Plugins
     cli: Internal CLIs
     internalPlugins: Internal Plugins
+    buildReportPlugin: Build Report Plugin
+    bundlerReportPlugin: Bundler Report Plugin
+    injectionPlugin: Injection Plugin
     gitPlugin: Git Plugin
-    contextPlugin: Global Context Plugin
 
     state internalPlugins {
+        buildReportPlugin
+        bundlerReportPlugin
         gitPlugin
-        contextPlugin
+        injectionPlugin
     }
 
     state core {
@@ -108,8 +120,10 @@ stateDiagram-v2
     }
 
     state published {
-        webpackplugin
         esbuildplugin
+        viteplugin
+        rollupplugin
+        webpackplugin
     }
 
     state plugins {
@@ -134,14 +148,14 @@ stateDiagram-v2
         customplugin32
     }
 
-    plugins --> factory: CONFIG_KEY\nhelpers\ntypes\ngetPlugins()
+    plugins --> factory: CONFIG_KEY<br/>helpers<br/>types<br/>getPlugins()
     core --> tools: types
-    core --> factory: Internal Plugins\ntypes
-    core --> plugins: getLogger()\ntypes
+    core --> factory: Internal Plugins<br/>types
+    core --> plugins: getLogger()<br/>types
     core --> tests: types
     factory --> plugins: Global Context
     factory --> published: Unplugin Factory
-    published --> NPM: types\nhelpers\ndatadogBundlerPlugin
+    published --> NPM: types<br/>helpers<br/>datadogBundlerPlugin
 ```
 
 ## Create a new plugin
@@ -153,17 +167,11 @@ Bootstrapping all the files you'll need to start coding.
 yarn cli create-plugin
 ```
 
-## Tests
-
-```bash
-# Build and run all the tests at once.
-yarn test
+Then learn more about what you can use from [the ecosystem](./packages/core).
 
-# Only run the tests. Useful to target a specific file.
-yarn test:only <path>
-```
+## Tests
 
-More details in the [tests README](./packages/tests#readme).
+<kbd>[📝 Full testing documentation ➡️](./packages/tests#readme)</kbd>
 
 > [!IMPORTANT]
 > If you're modifying a behavior or adding a new feature, update/add the required tests to your PR.
@@ -248,6 +256,8 @@ It will:
 -   update headers of each files.
 -   update `LICENSES-3rdparty.csv`, `LICENSE`, `NOTICE` and `README.md` with the correct licenses.
 
+It is also run part of the `yarn cli integrity` CLI.
+
 ## Documentation
 
 We try to keep the documentation as up to date as possible.

diff --git a/README.md b/README.md
@@ -324,57 +324,84 @@ Your function will receive two arguments:
 - `options`: The options you passed to the main plugin (including your custom plugins).
 - `context`: The global context shared accross our plugin.
 
-
+<!-- #global-context-type -->
 ```typescript
 type GlobalContext = {
-    // Available from the initialization.
+    // Mirror of the user's config.
     auth?: {
         apiKey?: string;
     };
-    // Available from the initialization.
     // More details on the currently running bundler.
     bundler: {
         name: string;
         fullName: string; // Including its variant.
-        outDir: string;
+        outDir: string; // Output directory
+        // Added in `buildStart`.
         rawConfig?: any;
-        variant?: string; // Major version of the bundler (webpack 4, webpack 5)
+        variant: string; // Major version of the bundler (webpack 4, webpack 5), empty string otherwise.
     };
-    // Available from `writeBundle`.
+    // Added in `writeBundle`.
     build: {
         errors: string[];
         warnings: string[];
-        entries?: { filepath: string; name: string; size: number; type: string, inputs: Input[], outputs: Output[] }[];
-        inputs?: { filepath: string; name: string; size: number; type: string, dependencies: Input[]; dependents: Input[] }[];
-        outputs?: { filepath: string; name: string; size: number; type: string, inputs: (Input | Output)[] }[];
+        // The list of entries used in the build.
+        entries ? : {
+            filepath: string;
+            inputs: Input[],
+            name: string;
+            outputs: Output[]
+            size: number;
+            type: string,
+        } [];
+        // The list of inputs used in the build.
+        inputs ? : {
+            filepath: string;
+            dependencies: Input[];
+            dependents: Input[]
+            name: string;
+            size: number;
+            type: string,
+        } [];
+        // The list of outputs generated by the build.
+        outputs ? : {
+            filepath: string;
+            name: string;
+            size: number;
+            type: string,
+            // Sourcemaps will use Outputs as their Inputs.
+            inputs: (Input | Output)[]
+        } [];
         start?: number;
         end?: number;
         duration?: number;
         writeDuration?: number;
     };
-    // Available from the initialization.
     cwd: string;
-    // Available from `buildStart`.
+    // Added in `buildStart`.
     git?: {
         hash: string;
         remote: string;
         trackedFilesMatcher: [TrackedFilesMatcher](packages/core/src/plugins/git/trackedFilesMatcher.ts);
     };
-    // Available from the initialization.
+    inject: (item: { type: 'file' | 'code'; value: string; fallback?: @self }) => void;
     start: number;
-    // Available from the initialization.
     version: string;
 }
 ```
 
-Your function will need to return an array of [Unplugin Plugins definitions](https://unplugin.unjs.io/guide/#supported-hooks).
-
 > [!NOTE]
-> Some parts of the context are only available after certain hooks.
+> Some parts of the context are only available after certain hooks:
+>   - `context.bundler.rawConfig` is added in the `buildStart` hook.
+>   - `context.build.*` is populated in the `writeBundle` hook.
+>   - `context.git.*` is populated in the `buildStart` hook.
+
+<!-- #global-context-type -->
+
+Your function will need to return an array of [Unplugin Plugins definitions](https://unplugin.unjs.io/guide/#supported-hooks).
 
 ## Contributing
 
-Check out the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
+Check out [CONTRIBUTING.md](CONTRIBUTING.md) for more information about how to work with the build-plugins ecosystem.
 
 ## License