{"id":13574476,"url":"https://github.com/RSC-Labs/backstage-changelog-plugin","last_synced_at":"2025-04-04T15:31:06.336Z","repository":{"id":199096044,"uuid":"700430424","full_name":"RSC-Labs/backstage-changelog-plugin","owner":"RSC-Labs","description":"ChangeLog plugin for Backstage which provides possibility to read and view change log of component in Software Catalog","archived":false,"fork":false,"pushed_at":"2024-04-19T15:31:21.000Z","size":515,"stargazers_count":3,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-26T00:24:35.633Z","etag":null,"topics":["backstage","changelog","plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RSC-Labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-04T15:25:31.000Z","updated_at":"2024-06-23T17:56:46.549Z","dependencies_parsed_at":"2024-06-23T17:54:51.107Z","dependency_job_id":"8119ec8d-a2a5-4b4c-8e23-093821c594c6","html_url":"https://github.com/RSC-Labs/backstage-changelog-plugin","commit_stats":null,"previous_names":["rsc-labs/backstage-changelog-plugin"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RSC-Labs%2Fbackstage-changelog-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RSC-Labs%2Fbackstage-changelog-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RSC-Labs%2Fbackstage-changelog-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RSC-Labs%2Fbackstage-changelog-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RSC-Labs","download_url":"https://codeload.github.com/RSC-Labs/backstage-changelog-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247202656,"owners_count":20900825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backstage","changelog","plugin"],"created_at":"2024-08-01T15:00:51.930Z","updated_at":"2025-04-04T15:31:01.328Z","avatar_url":"https://github.com/RSC-Labs.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# @rsc-labs/changelog-plugin\n\n\u003cimg src='./docs/plugin_icon.png' width='100' height='150' alt='Changelog card screenshot'\u003e\n\nBackstage Changelog Plugin is configurable and customizable plugin for viewing a changelog.\nYou can write your own parser, use [SemVer](https://semver.org/) parser or use default one, which follows [Keep the changelog](https://keepachangelog.com/) notation.\n\n### What is Changelog, why and who needs it?\nDescription from [Keep the changelog](https://keepachangelog.com/).\n\nA changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.\nIt is being created to make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.\nPeople need changelog. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.\n\n# Getting started\n\nIf you haven't already, check out the [Backstage docs](https://backstage.io/docs/getting-started/) and create a Backstage application with\n```\nnpx @backstage/create-app\n```\n\nThen, you will need to install and configure the changelog plugins for the frontend and the backend.\n\n## Frontend plugin\n\nInstall:\n```bash\ncd packages/app\nyarn add @rsc-labs/backstage-changelog-plugin\n```\n\nYou have two options how you can use Changelog functionality.\n\n### Card in Overview page:\n\nAdd the card to `packages/app/src/components/catalog/EntityPage.tsx`:\n```jsx\n// import:\nimport { EntityChangelogCard } from '@rsc-labs/backstage-changelog-plugin';\n\n// use it in entity view\nconst overviewContent = (\n  \u003cGrid container\n  ...\n    \u003cGrid item md={6} xs={12}\u003e\n      \u003cEntityChangelogCard /\u003e\n    \u003c/Grid\u003e\n  \u003c/Grid\u003e\n)\n```\n\n\u003cimg src='./docs/changelog_entity_card.png' alt='Changelog card screenshot'\u003e\n\n### Table in separated tab\n\nAdd content to `packages/app/src/components/catalog/EntityPage.tsx`:\n```jsx\n// import:\nimport { EntityChangelogContent } from '@rsc-labs/backstage-changelog-plugin';\n\nconst serviceEntityPage = (\n  \u003cEntityLayout\n  ...\n    \u003cEntityLayout.Route path=\"/changelog\" title=\"Changelog\"\u003e\n      \u003cEntityChangelogContent/\u003e\n    \u003c/EntityLayout.Route\u003e\n  \u003c/Grid\u003e\n)\n```\n\n\u003cimg src='./docs/changelog_entity_content.png' alt='Changelog content screenshot'\u003e\n\n### Check if annotations are ok\n\nYou can also check before if annotations are configured properly and depends on the result add EntityChangelogContent or EntityChangelogCard.\nTwo methods are exported:\n```jsx\nexport const isChangelogAnnotationConfigurationOk = (entity: Entity) : boolean\n```\nIt checks if configuration of annotations is ok.\n```jsx\nexport const getInfoAboutChangelogAnnotationConfiguration = (entity: Entity)\n```\nIt return information what is wrong with configuration of annotations.\n\n### Frontend configuration\n\nWe have created parser, which shall be able to parse English version of [Keep the changelog](https://keepachangelog.com/). We have a [SemVer](https://semver.org/) parser also available.\nIf you have different notation in your organization, you can define your own parser and pass it to the plugin.\n\nFor details see: [How to create own parser?](/plugins/backstage-changelog-plugin/README.md#how-to-create-my-own-parser)\n\n\n### Changing parser to a SemVer\n \n \n```jsx\nimport { semverParser } from '@rsc-labs/backstage-changelog-plugin';\n...\n\u003cGrid item md={6} xs={12}\u003e\n    \u003cEntityChangelogCard parser={semverParser} /\u003e\n\u003c/Grid\u003e\n```\n\n\u003cimg src='./docs/changelog_semver_entity_card.png' alt='Changelog semver content screenshot'\u003e\n\n\n## Backend plugin\n\nInstall:\n```bash\ncd packages/backend\nyarn add @rsc-labs/backstage-changelog-plugin-backend\n```\n\nCreate a file `packages/backend/src/plugins/changelog.ts`:\n```typescript\nimport {\n    createRouter,\n  } from '@rsc-labs/backstage-changelog-plugin-backend'\n  import { Router } from 'express';\n  import { PluginEnvironment } from '../types';\n  \n  export default async function createPlugin(\n    env: PluginEnvironment,\n  ): Promise\u003cRouter\u003e {\n    return await createRouter({\n      discovery: env.discovery,\n      tokenManager: env.tokenManager,\n      logger: env.logger,\n      reader: env.reader\n    });\n  }\n```\n\nAdd the plugin to `packages/backend/src/index.ts`:\n```typescript\n// import:\nimport changelog from './plugins/changelog';\n...\n\nasync function main() {\n  ...\n  // add env\n  const changelogEnv = useHotMemoize(module, () =\u003e createEnv('changelog'));\n  ...\n  // add to router\n  apiRouter.use('/changelog', await changelog(changelogEnv));\n  ...\n}\n```\n\nBackend plugin supports 3 fields, which can be used for reading a Changelog.\nChangelog itself is related to entity, so configuration is done by Annotations.\n```yaml\napiVersion: backstage.io/v1alpha1\nkind: Component\nmetadata:\n  name: example-website\n  annotations:\n    backstage.io/source-location: \"file:/home/backstage/backstage-changelog/examples/\"\n    changelog-file-ref: \"url:https://github.com/RSC-Labs/backstage-changelog-plugin/tree/main/CHANGELOG.md\"\n    changelog-name: \"CHANGELOG_CUSTOM_NAME.md\"\n\n```\nPlugin uses following logic:\n1) If \"changelog-file-ref\" is provided it takes precedence over other options, so it is used for reading a Changelog\n2) If not provided, then plugin check is \"changelog-name\" is provided. If yes, then it uses \"backstage.io/source-location\" as a location path together with \"changelog-name\"\n3) If no above options are provided, plugin uses \"backstage.io/source-location\" for reading a file named \"CHANGELOG.md\".\n\nBoth \"file\" and \"url\" options are supported.\n\n## TODO\n\n[ ] Unit tests\n\n[ ] Move logic from frontend to backend\n\n## Contribution\n\nContributions are welcome and they are greatly appreciated!\n\n## License\n\nLicensed under the Mozilla Public License, Version 2.0: https://www.mozilla.org/en-US/MPL/2.0/\n\n---\n\n© 2023 RSC https://rsoftcon.com/","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRSC-Labs%2Fbackstage-changelog-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRSC-Labs%2Fbackstage-changelog-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRSC-Labs%2Fbackstage-changelog-plugin/lists"}