diff --git a/.github/vale/config/vocabularies/Backstage/accept.txt b/.github/vale/config/vocabularies/Backstage/accept.txt index 2cbcc484f7..436021eb3d 100644 --- a/.github/vale/config/vocabularies/Backstage/accept.txt +++ b/.github/vale/config/vocabularies/Backstage/accept.txt @@ -176,6 +176,7 @@ idempotency Iglesias iLert img +impactful incentivised Indal indexable @@ -368,6 +369,8 @@ scaffolded scaffolder Scaffolder scrollbar +SCM +SCMs sdks seb semlas diff --git a/docs/plugins/guides.md b/docs/plugins/guides.md new file mode 100644 index 0000000000..a6bca91cdc --- /dev/null +++ b/docs/plugins/guides.md @@ -0,0 +1,56 @@ +--- +id: guides +title: Guides for Plugins +--- + +:::note Note +This docs is still a work in progress, many of the guides described below do not exist yet. +::: + +## Guides for Plugin Development + +### For Beginners: Introduction to Plugin Development + +This section is designed for those new to plugin development. It covers the basics and provides a foundation for more advanced topics. + +- **Introduction to Plugin Development** + - Why build plugins? Introduction to the value and impact of plugins within Backstage. + - Detailed guidance on starting and iterating on a plugin development project. + - Engaging with the community and stakeholders to propel your project. + +### For Intermediate Users: Scaling and Deploying Your Plugin + +This section helps developers prepare their plugins for broader adoption, emphasizing best practices in monitoring, logging, and performance. + +- **Scaling and Deploying Your Plugin** + - Strategies for scaling your plugin for greater adoption. + - Best practices for monitoring and logging. + - Understand plugin ownership and maintain an inner source mentality. + +### For Advanced Users: Advanced Plugin Customization and Integration + +This is for those ready to explore complex challenges and enhance their plugins with advanced features. + +- **Advanced Plugin Customization and Integration** + - Enabling resource-level authorization and interfacing with external services, SCMs, or databases. + - In-depth exploration of fostering an inner source mentality and understanding adoption dynamics. + - Decision-making frameworks: choosing between developing a new plugin or utilizing an existing open-source solution. + - Open-sourcing: How and when to contribute back to the community. + +## Additional Resources and Further Reading + +- **Real-world Implementations and Lessons** + + - [Case studies and examples from the community](https://github.com/backstage/community#newsletters). + - Best practices derived from mature implementations. + - [Existing open-source community-maintained plugins](https://github.com/backstage/community-plugins). + +- **Resource Compendium** + + - [Backstage Glossary](https://backstage.io/docs/references/glossary) of key terms. + - Recommended readings and tools for advanced developers. + +- **Certification and Learning Pathways** + - Pathways to deepen your understanding and expertise in plugin development for Backstage. + +Stay tuned for detailed exploration and guidance in each of these modules. We're excited to accompany you on your plugin development journey! diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 94de3bc482..f709afa894 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -1,36 +1,25 @@ --- id: index -title: Intro to plugins -description: Documentation on Introduction to Plugins +title: Introduction to Plugins +description: Learn about integrating various infrastructure and software development tools into Backstage through plugins. --- -Backstage is a single-page application composed of a set of plugins. +Backstage orchestrates a cohesive single-page application by seamlessly integrating various plugins. -Our goal for the plugin ecosystem is that the definition of a plugin is flexible -enough to allow you to expose pretty much any kind of infrastructure or software -development tool as a plugin in Backstage. By following strong -[design guidelines](../dls/design.md) we ensure the overall user experience -stays consistent between plugins. +Our vision for the plugin ecosystem champions flexibility, empowering you to incorporate a broad spectrum of infrastructure and software development tools into Backstage as plugins. Adherence to stringent [design guidelines](../dls/design.md) guarantees a consistent and intuitive user experience across the entire plugin landscape. -![plugin](../assets/plugins/my-plugin_screenshot.png) +![Plugin Screenshot](../assets/plugins/my-plugin_screenshot.png) -## Creating a plugin +## Creating a Plugin -To create a plugin, follow the steps outlined [here](create-a-plugin.md). +Embark on your plugin development journey by following the detailed steps provided in the [Create a Plugin](create-a-plugin.md) documentation. -## Suggesting a plugin +## Suggesting a Plugin -If you start developing a plugin that you aim to release as open source, we -suggest that you create a -[new Issue in the community plugins repo](https://github.com/backstage/community-plugins/issues/new/choose). -This helps the community know what plugins are in development. +If you're developing an open-source plugin, we encourage you to create a [new issue in the community plugins repository](https://github.com/backstage/community-plugins/issues/new/choose). This informs the community about upcoming plugins and invites collaboration and feedback. -You can also use this process if you have an idea for a good plugin but you hope -that someone else will pick up the work. +This approach is equally beneficial if you conceive an idea for a potentially impactful plugin but prefer if another contributor undertakes its development. -## Integrate into the Software Catalog +## Integration with the Software Catalog -If your plugin isn't supposed to live as a standalone page, but rather needs to -be presented as a part of a Software Catalog (e.g. a separate tab or a card on -an "Overview" tab), then check out -[the instruction](integrating-plugin-into-software-catalog.md) on how to do it. +Should your plugin complement the Software Catalog rather than exist as a standalone feature (for instance, as an additional tab or a card within an "Overview" tab), you'll find comprehensive guidance on achieving this integration in the [Integrating Plugin into Software Catalog guide](integrating-plugin-into-software-catalog.md).