|
|
|
@@ -17,6 +17,7 @@ If you need help, just jump into our [Discord chatroom](https://discord.gg/backs
|
|
|
|
|
- [Accessibility](#accessibility)
|
|
|
|
|
- [Get Started!](#get-started)
|
|
|
|
|
- [Coding Guidelines](#coding-guidelines)
|
|
|
|
|
- [AI Use Policy and Guidelines](#ai-use-policy-and-guidelines)
|
|
|
|
|
- [Documentation Guidelines](#documentation-guidelines)
|
|
|
|
|
- [Package Scripts](#package-scripts)
|
|
|
|
|
- [Local configuration](#local-configuration)
|
|
|
|
@@ -128,6 +129,37 @@ If there are any updates in `markdown` file please make sure to run `yarn run li
|
|
|
|
|
|
|
|
|
|
The Backstage development environment does not require any specific editor, but it is intended to be used with one that has built-in linting and type-checking. The development server does not include any checks by default, but they can be enabled using the `--check` flag. Note that using the flag may consume more system resources and slow things down.
|
|
|
|
|
|
|
|
|
|
## AI Use Policy and Guidelines
|
|
|
|
|
|
|
|
|
|
Our goal in the Backstage project is to develop an excellent software system. This requires careful attention to detail in every change we integrate. Maintainer time and attention is very limited, so it's important that changes you ask us to review represent your _best_ work.
|
|
|
|
|
|
|
|
|
|
You are encouraged to use tools that help you write good code, including AI tools. However, you always need to understand and explain the changes you're proposing to make, whether or not you used an LLM as part of your process to produce them. The answer to "Why did you make change X?" should never be "I'm not sure. The AI did it."
|
|
|
|
|
|
|
|
|
|
**Do not submit an AI-generated PR you haven't personally understood and tested**, as this wastes maintainers' time. PRs that appear to violate this guideline will be closed without review. If you do submit a largely AI-generated PR, clearly mark it as such in the description—maintainers may still close it without further review if it does not seem worthwhile.
|
|
|
|
|
|
|
|
|
|
### Using AI as a Coding Assistant
|
|
|
|
|
|
|
|
|
|
1. Don't skip **becoming familiar with the part of the codebase** you're working on. This will let you write better prompts and validate their output if you use an LLM. Code assistants can be a useful search engine/discovery tool in this process, but don't trust claims they make about how Backstage works. LLMs are often wrong, even about details that are clearly answered in the [Backstage documentation](https://backstage.io/docs).
|
|
|
|
|
2. Split up your changes into **coherent commits**, even if an LLM generates them all in one go. See our section on [Creating Changesets](#creating-changesets) for guidance on documenting your changes.
|
|
|
|
|
3. Don't simply ask an LLM to add **code comments**, as it will likely produce a bunch of text that unnecessarily explains what's already clear from the code. If using an LLM to generate comments, be really specific in your request, demand succinctness, and carefully edit the result.
|
|
|
|
|
|
|
|
|
|
### Using AI for Communication
|
|
|
|
|
|
|
|
|
|
Backstage contributors are expected to communicate with intention, to avoid wasting maintainer time with long, sloppy writing. We strongly prefer clear and concise communication about points that actually require discussion over long AI-generated comments.
|
|
|
|
|
|
|
|
|
|
When you use an LLM to write a message for you, it remains **your responsibility** to read through the whole thing and make sure that it makes sense to you and represents your ideas concisely. A good rule of thumb is that if you can't make yourself carefully read some LLM output that you generated, nobody else wants to read it either.
|
|
|
|
|
|
|
|
|
|
Here are some concrete guidelines for using LLMs as part of your communication workflows:
|
|
|
|
|
|
|
|
|
|
1. When writing a pull request description, **do not include anything that's obvious** from looking at your changes directly (e.g., files changed, functions updated, etc.). Instead, focus on the _why_ behind your changes. Don't ask an LLM to generate a PR description on your behalf based on your code changes, as it will simply regurgitate the information that's already there.
|
|
|
|
|
2. Similarly, when responding to a pull request comment, **explain _your_ reasoning**. Don't prompt an LLM to re-describe what can already be seen from the code.
|
|
|
|
|
3. Verify that **everything you write is accurate**, whether or not an LLM generated any part of it. Backstage's maintainers will be unable to review your contributions if you misrepresent your work (e.g., wrongly describing your code changes, their effect, or your testing process).
|
|
|
|
|
4. Complete all parts of the **PR description template**, including screenshots and the checklist. Don't simply overwrite the template with LLM output.
|
|
|
|
|
5. **Clarity and succinctness** are much more important than perfect grammar, so you shouldn't feel obliged to pass your writing through an LLM. If you do ask an LLM to clean up your writing style, be sure it does _not_ make it longer in the process. Demand succinctness in your prompt.
|
|
|
|
|
6. Quoting an LLM answer is usually less helpful than linking to **relevant primary sources**, like source code, [Backstage documentation](https://backstage.io/docs), or reference materials. If you do need to quote an LLM answer in a discussion, clearly distinguish LLM output from your own thoughts.
|
|
|
|
|
|
|
|
|
|
If you have questions about AI usage or need help, feel free to ask in [Discord](https://discord.gg/backstage-687207715902193673).
|
|
|
|
|
|
|
|
|
|
## Documentation Guidelines
|
|
|
|
|
|
|
|
|
|
Contributing to the docs is one of the best ways to start getting involved with Backstage. The documentation site is often the first stop for anyone using or exploring Backstage, so even small improvements can have a big impact!
|
|
|
|
|
Patrik Oldsberg