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

Merge pull request #28865 from backstage/sennyeya/guide-template

Browse Source 
feat(docs): start preparing a golden path
This commit is contained in:
Aramis Sennyey
2025-03-07 08:16:16 -05:00
committed by GitHub
parent 575c32c8f5 0acbd34276
commit 4a76871708
7 changed files with 315 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plugins/guides/101/meta.md
-33
View File
@@ -1,33 +0,0 @@
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
# Intro to Plugin Development
## Writing Guidelines
The goal of this section is to take the reader from zero-to-situated. Docs should assume that the user has _only_ gone through the initial getting started docs. At the end of this guide, the user will understand the basics of plugin development.
### Why build plugins?
This section should answer definitely why you should build a new plugin. The Backstage framework is deeply empowered by plugins and plugins are core to the project's success. Users should walk away from reading this section with a conviction that plugins are the right path for new functionality.
### Creating a plugin
This section should be extremely deliberate in showing readers every step of the way to create a plugin using Backstage's best practises. A reader that finishes this section should feel extremely comfortable adding and installing new plugins regardless of their experience with JS/TS and Backstage.
- Setting up your environment
- Scaffolding a new plugin
- Installation syntax
- Core services
- Debugging
- Declaration error, `export default` missing
- Startup error, `httpRouter` failed to start
### Sustainable plugin development
Plugins are not developed in a vacuum. Users should reach for them to solve specific business problems facing their developers, for example, you may be tasked to create
- a new vendor integration like PagerDuty,
- a new plugin backend that talks to an internal service,
- etc.
This section should contain learnings from successful Backstage deployments about how to engage with stakeholders, how/when to iterate on your plugin, and setting yourself up for future success.
docs/plugins/guides/index.md
-56
View File
@@ -1,56 +0,0 @@
---
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!
docs/plugins/guides/meta.md
-18
View File
@@ -1,18 +0,0 @@
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
## Glossary
- Page: A single `md` file.
- Guide: A number of pages grouped under the same folder.
- Progression: Guides are ordered and moving along that order will give you the next guide, for example, "201" will follow "101" or "experienced" will follow "beginner".
- Progression level: Explicit guides in a progression, for example, "101" or "beginner"
## Writing Guidelines
The goal of these docs is to provide a comprehensive set of guides that developers + admins can use to quickly get up to speed with plugin development, and then refer to as they're developing their own plugins.
A user that finishes all of these guides will feel comfortable implementing plugins on their own. If additional assistance is required, they should be referred to other sources of information such as Discord, GitHub, source code, or documentation for further support. The user will also understand why/when to build their own plugins, inner-sourcing their developer portal and contributing internal plugins back to the open-source project.
At the same time, not all users will finish the docs or they may come back to them as required. Individual guides should have strong "abstracts" (what will I learn by reading this guide), table of contents, and "next steps" (what do I need to do next) to guide users to read the most important pieces for their work.
When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone, when finishing one level (for example 101), you should be able to immediately jump into the next (201) without additional research or background. Referencing previous progression levels is ok.