✨ We would love for you to contribute to Janus IDP collection of Backstage plugins and help make it even better than it is today! ✨
As a contributor, here are the guidelines we would like you to follow:
- Code of conduct
- How can I contribute?
- Using the issue tracker
- Submitting a Pull Request
- Coding rules
- Working with the code
We also recommend that you read How to Contribute to Open Source.
Help us keep Janus-IDP open and inclusive. Please read and follow our Code of Conduct.
As a Janus-IDP user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, etc. Take a look at the documentation issues that need help.
Please follow the Documentation guidelines.
Issues that lack relevant information can be very difficult to track down and fix, please follow the Bug report guideline to help make them easier to resolve. Help make them easier to resolve by adding any relevant information.
Confirmed bugs and ready-to-implement features are marked with the help wanted label. Post a comment on an issue to indicate you would like to work on it and to request help from the @janus-idp/maintainers-plugins and the community.
Before opening an issue or a Pull Request, please use the GitHub issue search to make sure the bug or feature request hasn't been already reported or fixed.
A good bug report shouldn't leave others needing to chase you for more information. Please try to be as detailed as possible in your report and fill in the information requested in the bug report template.
Feature requests are welcome, but take a moment to find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible and fill in the information requested in the feature request template.
Plugins are a great way to extend Backstage capabilities and are an integral part of this repository. Please provide as much detail and context as possible and fill the information requested in the plugin suggestion template.
Good pull requests, whether patches, improvements, or new features, are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
Please ask first before embarking on any significant pull requests (e.g. implementing features, refactoring code), otherwise you risk spending a lot of time working on something that the project's maintainers might not want to merge into the project.
If you have never created a pull request before, welcome 🎉 😄. Here is a great tutorial on how to create one 🙂
Here is a summary of the steps to follow:
- Set up the workspace
- If you cloned a while ago, get the latest changes from upstream and update dependencies:
$ git checkout main
$ git pull upstream main
$ yarn install- Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:
$ git checkout -b <topic-branch-name>- Make your code changes, following the Coding rules
- Push your topic branch up to your fork:
$ git push origin <topic-branch-name>- Open a Pull Request with a clear title and description.
Tips:
- For ambitious tasks, open a Pull Request as soon as possible with the
[WIP]prefix in the title, in order to get feedback and help from the community. - Allow Janus-IDP maintainers to make changes to your Pull Request branch. This way, we can rebase it and make some minor changes if necessary. All changes we make will be done in the new commit, and we'll ask for your approval before merging them.
To ensure consistency and quality throughout the source code, all code modifications must have:
- No linting errors
- A test for every possible case introduced by your code change
- 100% test coverage
- Valid commit message(s)
- Documentation for new features
- Updated documentation for modified features
While our linter configuration already cover most of the code styling, it is not always helpful when it comes how the code should be structured. Here's a list of few conventions we follow according to file names, and folder structure:
- Backstage plugins and supporting libraries live inside the
pluginsfolder. Each plugin has its own folder named after the plugin id. For example, the@janus-idp/backstage-plugin-topologyplugin lives inside theplugins/topologyfolder. packagesfolder contains all NPM packages that are notpluginrelated. For example, a local backstage instance lives inside thepackages/appandpackages/backendfolders. Additionally the@janus-idp/janus-clipackage lives inside thepackages/janus-clifolder since this is not a plugin.- Plugin names are always prefixed with
@janus-idp/backstage-plugin-and the plugin id. For example, the@janus-idp/backstage-plugin-topologyplugin has thetopologyid. Please always useyarn newwhen creating a new plugin. It will guide you through the process and ensure the plugin id is used consistently. - Each plugin contains a
devfolder. This is folder is used for development setup. Please try to make your plugin development self-contained so you don't have to rely on changes inpackagesfolder. This is not always possible, but we try to keep thepackagesfolder as clean as possible. - Each plugin contains a
README.md. This file contains the user facing documentation. Please follow the Documentation guidelines when writing documentation. - Each plugin contains a
CONTRIBUTING.md. This file contains the plugin contributor and developer documentation. Please follow the Documentation guidelines when writing documentation. - Within
srcfolder there are various additional folders depending on your plugin role. We follow following convention:apifolder contains API clients for third party servicescomponentsfolder contains React components exposed from the pluginhooksfolder contains React hookslibfolder contains all other code that is not exposed from the plugin, helper utilities etc.servicefolder contains the plugin backend service. This is most commonly a Backstage sub-router that is then exposed via the Backstage backend APIprovidersfolder contains the plugin's entity providers exposed from the pluginactionsfolder contains GPT/Scaffolder actions exposed from the plugin
To ensure consistency and quality, all documentation modifications must:
- Refer to brand in bold with proper capitalization, i.e. GitHub, Red Hat, Backstage, npm
- Prefer tables over lists when listing key values, i.e. List of options with their description
- Use links when you are referring to:
- a Janus-IDP concept described somewhere else in the documentation, i.e. How to contribute
- a third-party product/brand/service, i.e. Integrate with GitHub
- an external concept or feature, i.e. Create a GitHub release
- a package or module, i.e. The
@janus-idp/backstage-plugin-topologymodule
- Use the single backtick
codequoting for:- commands inside sentences, i.e. the
yarn newcommand - programming language keywords, i.e.
function,async,String - packages or modules, i.e. The
@janus-idp/backstage-plugin-topologymodule
- commands inside sentences, i.e. the
- Use the triple backtick
codeformatting for:- code examples
- configuration examples
- sequence of command lines
When adding a new plugin, provide a clear guide into how to use it. This includes:
- Installation instructions
- Development setup, including how to set up all necessary third party integrations
- Comprehensively describe all available configuration options
- Screenshots or Videos showcasing UI elements of the plugin
We do not enforce strict commit message guidelines, instead we resort to Atomic PRs and Squash and merge strategy to ensure that the commit history is clean and readable. However please keep in mind that your individual commit messages will be visible in the PR history and will be used to generate the commit message of the final merge commit. Therefore please keep the following guidelines in mind when writing commit messages and refrain from meaningless, non-descriptive commit messages like "update" or "fix issues", etc.
If possible, make atomic commits, which means:
- a commit should contain exactly one self-contained functional change
- a functional change should be contained in exactly one commit
- a commit should not create an inconsistent state (such as test errors, linting errors, partial fixes, feature with documentation, etc.)
A complex feature can be broken down into multiple commits as long as each one maintains a consistent state and consists of a self-contained change.
Following these guidelines for committing messages is optional but strongly encouraged.
Each commit message consists of a header and a body. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
The header is mandatory and the scope of the header is optional.
The body can contain a closing reference to an issue.
Following these guidelines for Pull Request messages is required and will be enforced by the CI. This is a strong prerequisite for our release automation.
Each pull request consists of a title and a body
The title has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit.
The body should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.
The type must be one of the following:
| Type | Description |
|---|---|
| fix | A bug fix |
| feat | A new feature |
| chore | A change that doesn't affect package codebase but rather the tooling around |
| docs | Documentation only changes |
| style | Changes that do not affect the meaning of the code (white space, formatting, missing semicolons, etc.) |
| refactor | A code change that neither fixes a bug nor adds a feature |
| perf | A code change that improves performance |
| test | Adding missing tests or correcting existing tests |
| revert | Reverts a given commit |
Type can contain optional scope and ! to mark breaking changes. Please use scope to denote the affected plugin or package.
The subject contains a succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize the first letter
- no dot (.) at the end
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.
It should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes.
Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines.
The rest of the commit message is then used for this.
fix(pencil): stop graphite breaking when too much pressure applied
feat(pencil): add 'graphiteWidth' option
Fix #42
perf(pencil)!: remove graphiteWidth option
BREAKING CHANGE: The graphiteWidth option has been removed.
The default graphite width of 10mm is always used for performance reasons.
Fork the project, clone your fork, configure the remotes and install the dependencies:
# Clone your fork of the repo into the current directory
$ git clone git@github.com:$(gh config get user -h github.com)/backstage-plugins.git
# Navigate to the newly cloned directory
$ cd backstage-plugins
# Assign the original repo to a remote called "upstream"
$ git remote add upstream git@github.com:janus-idp/backstage-plugins.git
# Install the dependencies
$ yarn installThe Backstage has multiple dependencies. To pass through their installation, make sure to follow the isolated-vm requirements.
The backstage-plugins repository use ESLint for linting and Prettier for formatting.
Formatting will be automatically verified and fixed by lint-staged on the commit.
Before pushing your code changes make sure there are no linting errors with yarn lint and yarn prettier:check.
Tips:
- Most linting errors can be automatically fixed with
yarn prettier:fix.
The backstage-plugins repository uses Jest for writing and running tests.
Before pushing your code changes make sure all tests pass and the coverage is 100%:
$ yarn testThis repository defaults to a rapid release scheme where we would rather release on every PR merge than restrict ourselves by a strict release cadence and policy. This brings contributors the opportunity to see the direct impact of their contributions since they are released immediately after the merge. The release process itself is done via the semantic-release tool. In order for it to work properly, it requires contributors to follow a simple set of rules:
- Never bump the package version manually yourself.
semantic-releasewill calculate the appropriate version change and do it for you. - Do not hesitate to update multiple packages in a single PR. multi-semantic-release will take care of it, and release a new version for all of them while updating their cross-dependencies accordingly.
Semantic Release does the following:
- Analyze commits for each package to determine if a release is necessary (if there are changes in the package)
- Generates
CHANGELOG.mdfor each package to be released - Bump the version number in the
package.jsonfor each package - Creates a git tag
<package-name>@<version>pointing to the new release - Create a new GitHub release for each package
- Publishes the new version to the NPM registry
semantic-release uses the Pull request title to determine the consumer impact of changes in the codebase. Following formalized conventions for Pull request title messages, semantic-release automatically determines the next semantic version number, generates a changelog, and publishes the release. Please read the pull request message format section for more details.
The table below shows which Pull Request titles get you which release:
| Release type | Type and scope that triggers it | Commit message example |
|---|---|---|
vX.Y.🆙 Fix Release |
Type must be fix, docs, refactor, style, revert or chore(deps) (in this case the scope must match) |
fix(topology): fix pipelinerun status icon color |
vX.🆙.0 Feature Release |
Type must be feat, perf |
feat(kiali): add namespace selector |
v🆙.0.0 Breaking Release |
<type>(<optional-scope>)!: <message> Notice the ! token. It must be present. The type and scope are irrelevant. |
feat(ocm)!: Relocate OCM config and support multiple hubs |
| No release | Type chore (except when the scope is deps), or for any type when the scope is no-release |
A particular case of contribution is implementing a new plugin. Before you start implementing a new one, please consult our issue tracker and make a New plugin request. Once you have a green light from the community, you can start implementing your plugin.
Start by running our plugin template wizard:
yarn newThis will lead you through plugin category selection and set up all the required boilerplate. By default, this will only create a new standalone plugin within the plugins folder and will not touch the packages folder where we host an empty Backstage instance. You can bypass this behavior by running janus-cli new directly instead, but we discourage it. We aim to enable a standalone, self-contained plugin development workspace, however this is not fully possible at this moment.
This interactive wizard will lead you through the process of creating a new plugin. It will ask you for the following information:
- Plugin type You are offered a choice from the following options:
| Option | Description | Package name | Folder name |
|---|---|---|---|
| plugin | A new frontend plugin. React-based frontend plugin. | @janus-idp/backstage-plugin-<ID> |
plugins/<ID> |
| backend-plugin | A new backend plugin. Plugin to the Node.js Express server. | @janus-idp/backstage-plugin-<ID>-backend |
plugins/<ID>-backend |
| scaffolder-module | An module exporting custom actions for @backstage/plugin-scaffolder-backend |
@janus-idp/backstage-plugin-scaffolder-backend-module-<ID> |
plugins/scaffolder-backend-module-<ID> |
| plugin-common | A new isomorphic common plugin package. Serves as an interface between other plugins. | @janus-idp/backstage-plugin-<ID>-common |
plugins/<ID>-common |
| backend-module | A new backend module | @janus-idp/backstage-plugin-<ID>-backend-module-<MODULE_ID> |
plugins/<ID>-backend-module-<MODULE_ID> |
| web-library | A new web-library package. Currently not used | @janus-idp/backstage-<ID> |
packages/<ID> |
| plugin-node | A new Node.js library plugin package. Currently not used | @janus-idp/backstage-plugin-<ID>-node |
plugins/<ID>-node |
| plugin-react | A new web library plugin package. Currently not used | @janus-idp/backstage-plugin-<ID>-react |
plugins/<ID>-react |
- Plugin id: This value is used in templating and determines the resulting package name and folder name. Please see the table above and look where the
<ID>is used. As you can see, you don't have to specify the plugin role within the ID value, the role is added to the package name automatically.
Once you finish bootstrapping your plugin folder, please look up the upstream documentation. For example:
- The structure of a plugin
- For frontend plugins, see the general plugin development guide and composability system.
- For backend plugins, see the backend specific plugin development guide.
Backstage's support for standalone plugin development is minimal (especially for backend plugins), therefore we include a minimal test instance within this repository.
- Install the plugin via
yarn workspace [app|backend] add @janus-idp/<PLUGIN_NAME>@*- Example:
yarn workspace app add "@janus-idp/backstage-plugin-nexus-repository-manager@*" @*at the end ensures the package is always linked to the local package in thepluginsfolder
- Example:
- Follow the plugin's install instructions
- (Optional) Tell git to assume the modified files are unchanged, so that
status/diff commands are representative of your current work:
# Example, list any dev app files where you don't want changes tracked git update-index --assume-unchanged \ app-config.yaml \ packages/app/package.json \ packages/app/src/components/catalog/EntityPage.tsx - Run
yarn start:backstage
In case your plugin supports standalone mode, you can use yarn start --filter=<PLUGIN_NAME> command in your plugin directory directly and you don't have to install the plugin as mentioned above.
If you want to start contributing to a plugin you're not yet familiar with, always consult its CONTRIBUTING.md file within its folder in plugins/. This file contains all the information you need to know about that particular plugin's development setup.
You can augment the configuration for a plugin by running yarn start --config <CONFIG_FILE>.
-
Error:
ERROR run failed: error preparing engine: Invalid persistent task configuration: You have <x - number> persistent tasks but `turbo` is configured for concurrency of 10. Set --concurrency to at least <x - number>
Solution: You need to run yarn start with a filter. e.g. yarn start --filter=<PLUGIN_NAME>