From f8b0197fc2aaa8d5e780f0199a11654218fe3e64 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 11 Apr 2022 15:18:21 +0200 Subject: [PATCH] docs: add section to help decide where to place code Signed-off-by: Patrik Oldsberg --- .../package-decision.drawio.svg | 269 ++++++++++++++++++ docs/overview/architecture-overview.md | 12 + 2 files changed, 281 insertions(+) create mode 100644 docs/assets/architecture-overview/package-decision.drawio.svg diff --git a/docs/assets/architecture-overview/package-decision.drawio.svg b/docs/assets/architecture-overview/package-decision.drawio.svg new file mode 100644 index 0000000000000..e5199adf3f038 --- /dev/null +++ b/docs/assets/architecture-overview/package-decision.drawio.svg @@ -0,0 +1,269 @@ + + + + + + + + + +
+
+
+ No +
+
+
+ + + No + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + +
+
+
+ Is the new addition public API? +
+ i.e. exported from the package +
+
+
+ + + Is the new addition public API?... + + + + + + + + + +
+
+
+ In what plugin package should I put my code? +
+
+
+ + + In what plugin package sho... + + + + + + + +
+
+
+ Put it in the package +
+ that uses it +
+
+
+ + + Put it in the package... + + + + + + + + +
+
+
+ Only app/backend +
+
+
+ + + Only app/backend + + + + + + + + + +
+
+
+ Is the export supposed +
+ to be used by other plugins or just app/backend packages? +
+
+
+ + + Is the export supposed... + + + + + + + +
+
+
+ Put it in the frontend or backend plugin package +
+
+
+ + + Put it in the frontend or... + + + + + + + + +
+
+
+ No +
+
+
+ + + No + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + +
+
+
+ Should the export be +
+ usable by both Node.js and browser packages? +
+
+
+ + + Should the export be... + + + + + + +
+
+
+ Yes, used by other plugins +
+
+
+ + + Yes, used by other plugins + + + + + + + +
+
+
+ Put frontend exports in <plugin>-react, and backend exports in <plugin>-node +
+
+
+ + + Put frontend exports in <p... + + + + + + + +
+
+
+ Add it to <plugin>-common, but be sure to support both Node.js and web environments +
+
+
+ + + Add it to <plugin>-common, but be... + + + + + + + + + + Viewer does not support full SVG 1.1 + + + + diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index 5b6b81cf100f9..382399e6034be 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -256,6 +256,18 @@ The Backstage CLI is in a category of its own and is depended on by virtually all other packages. It's not a library in itself though, and must always be a development dependency only. +### Deciding where you place your code + +It can sometimes be difficult to decide where to place your plugin code. For example +should it go directly in the `-backend` plugin package or in the `-node` package? +As a rule of thumb you should try to keep the exposure of your code as low +as possible. If it doesn't need to be public API, it's best to avoid. If you don't +need it to be used by other plugins, then keep it directly in the plugin packages. + +Below is a chart to help you decide where to place your code. + +![Package decision](../assets/architecture-overview/package-decision.drawio.svg) + ## Databases As we have seen, both the `lighthouse-audit-service` and `catalog-backend`