paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 20 Packages Projects Releases Wiki Activity

Update docs/features/software-catalog/extending-the-model.md

Browse Source 
Signed-off-by: Ben Lambert <blam@spotify.com>

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
This commit is contained in:
Ben Lambert
2021-09-11 03:09:56 +02:00
committed by GitHub
parent 06728d6273
commit 1f564b4dc1
1 changed files with 7 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/software-catalog/extending-the-model.md
+7 -8
View File
@@ -401,12 +401,11 @@ Example intent:
> "I have multiple versions of my API deployed in different environments so I
> want to have `mytool-dev` and `mytool-prod` as different entities."
Whilst it's possible to have different versions of different entities deployed
as separate entities, it's something we recommend against. We believe that a
developer should be able to just find one `Component` and be able to see the
different code versions that are deployed throughout your stack, and also
similarly for any other `kind` like `API` too.
While it's possible to have different versions of the same thing represented
as separate entities, it's something we generally recommend against. We believe that a
developer should be able to just find for example one `Component` representing a service, and to be able to see the
different code versions that are deployed throughout your stack within its view. This reasoning works similarly for other kinds as well, such as `API`.
When writing your custom plugins, we encourage the behavior to expect if
possible that you should be showing all the different variations through
environments etc under one canonical reference to your software in the catalog.
That being said - sometimes the differences between versions are so large, that they represent what is for all intents and purposes an entirely new entity as seen from the consumer's point of view. This can happen for example for different _significant_ major versions of an API, and in particular if the two major versions coexist in the ecosystem for some time. In those cases, it can be motivated to have one `my-api-v2` and one `my-api-v3` named entity. This matches the end user's expectations when searching for the API, and matches the desire to maybe have separate documentation for the two and similar. But use this sparingly - only do it if the extra modelling burden is outweighed by any potential better clarity for users.
When writing your custom plugins, we encourage designing them such that they can show all the different variations through environments etc under one canonical reference to your software in the catalog. For example for a continuous deployment plugin, a user is likely to be greatly helped by being able to see the entity's versions deployed in all different environments next to each other in one view. That is also where they might be offered the ability to promote from one environment to the other, do rollbacks, see their relative performance metrics, and similar. This coherency and collection of tooling in one place is where something like Backstage can offer the most value and effectiveness of use. Splitting your entities apart into small islands makes this harder.