{"id":20915783,"url":"https://github.com/brainelectronics/snippets2changelog","last_synced_at":"2025-05-13T10:33:36.503Z","repository":{"id":241889107,"uuid":"807988388","full_name":"brainelectronics/snippets2changelog","owner":"brainelectronics","description":"Generate a changelog from individual snippets","archived":false,"fork":false,"pushed_at":"2024-11-17T19:11:31.000Z","size":137,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-17T19:18:16.067Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brainelectronics.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2024-05-30T06:57:32.000Z","updated_at":"2024-11-17T19:10:43.000Z","dependencies_parsed_at":"2024-05-30T14:49:49.009Z","dependency_job_id":"8c6f3a65-c9c4-4a94-9f97-e910f803fc49","html_url":"https://github.com/brainelectronics/snippets2changelog","commit_stats":null,"previous_names":["brainelectronics/snippets2changelog"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Fsnippets2changelog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Fsnippets2changelog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Fsnippets2changelog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Fsnippets2changelog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brainelectronics","download_url":"https://codeload.github.com/brainelectronics/snippets2changelog/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225206833,"owners_count":17438200,"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":[],"created_at":"2024-11-18T16:18:20.842Z","updated_at":"2024-11-18T16:18:21.463Z","avatar_url":"https://github.com/brainelectronics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# snippets2changelog\n\n[![Downloads](https://pepy.tech/badge/snippets2changelog)](https://pepy.tech/project/snippets2changelog)\n![Release](https://img.shields.io/github/v/release/brainelectronics/snippets2changelog?include_prereleases\u0026color=success)\n![Python](https://img.shields.io/badge/Python-3.9%20|%203.10%20|%203.11-green.svg)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![codecov](https://codecov.io/github/brainelectronics/snippets2changelog/branch/main/graph/badge.svg)](https://app.codecov.io/github/brainelectronics/snippets2changelog)\n\nGenerate a changelog from individual snippets\n\n---------------\n\n\n## General\n\nCreate version info files based on the latest changelog entry.\n\n\u003c!-- MarkdownTOC --\u003e\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Info](#info)\n  - [Create](#create)\n    - [Snippet](#snippet)\n    - [Changelog](#changelog)\n  - [Parse](#parse)\n  - [CI](#ci)\n    - [GitHub](#github)\n      - [Actions](#actions)\n      - [Custom workflow](#custom-workflow)\n    - [Other](#other)\n- [Contributing](#contributing)\n  - [Setup](#setup)\n  - [Testing](#testing)\n  - [Changelog](#changelog-1)\n- [Credits](#credits)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n## Installation\n\n```bash\n[\u003cPYTHON\u003e -m] pip[3] install [--user] [--upgrade] snippets2changelog\n```\n\n## Usage\n\n### Info\n\nPrint informations about snippets2changelog\n\n```bash\nchangelog-generator info\n```\n\n### Create\n#### Snippet\n\nCreate a new snippet with the given name at the specified snippets folder\n\n```bash\nchangelog-generator create example_snippets/123.md\n```\n\n```\nShort description: My example snippet\nChoose from: ['bugfix', 'feature', 'breaking']\nType of change: feature\nChoose from: ['internal', 'external', 'all']\nScope of change: external\nAffected users (default all): testers\n```\n\n```\n## My example snippet\n\u003c!--\ntype: feature\nscope: external\naffected: testers, users\n--\u003e\n\nTBD\n\n```\n\n#### Changelog\n\nCreate or update a changelog with all snippets.\n\nThe generated changelog will be named `\u003cOLD_CHANGELOG_NAME.new\u003e` unless the\n`--in-place` flag is used. This flag is intended for CI usage with a clean\ncheckout before a run.\n\n*Be aware to restore the changelog before another run as it might generate\nversion entries and version bumps multiple times otherwise.*\n\n```bash\nchangelog-generator changelog changelog.md --snippets=.snippets [--in-place]\n```\n\nTo just get the latest changelog entry without updating or generating the\nchangelog, use `--dry-run` to print the latest snippet content in JSON format.\n\n```json\n{\n    \"version\": \"1.5.0\",\n    \"timestamp\": \"2024-10-12T13:36:46+02:00\",\n    \"meta\": {\n        \"type\": \"feature\",\n        \"scope\": [\n            \"all\"\n        ],\n        \"affected\": [\n            \"all\"\n        ]\n    },\n    \"content\": \"\\n\\nUse `--dry-run` with the `changelog` subparser to print the latest changelog entry as JSON instead of updating the changelog file.\\n\",\n    \"version_reference\": \"https://github.com/brainelectronics/snippets2changelog/tree/1.5.0\"\n}\n```\n\nThe option `--no-internal` ignores all snippets with scope `internal` during\nthe changelog generation. This is useful if those changes are not affecting\nthe \"product\" like internal documentation changes or similar things, which e.g.\ndo not require a deployment.\n\nThe option `--version-reference` allows to configure the URL to the tags in the\nrendered changelog file. Use e.g.\n`https://github.com/\u003cGITHUB_USER\u003e/\u003cPROJECT_USING_SNIPPETS2CHANGELOG\u003e/tree/`\nfor a project using this package.\n\n### Parse\n\nParse an existing snippet file and return the data as JSON without indentation\n\n```bash\nchangelog-generator parse example_snippets/123.md \\\n  --indent=4\n```\n\n```json\n{\n    \"type\": \"feature\",\n    \"scope\": [\n        \"external\"\n    ],\n    \"affected\": [\n        \"testers\",\n        \"users\"\n    ],\n    \"title\": \"My example snippet\",\n    \"details\": \"\\n\\nTBD\\n\"\n}\n```\n\n### CI\n\nTo use this tool in a CI environment use the following commands, job configs or\nactions.\n\n#### GitHub\n##### Actions\nSee [changelog-from-snippets](https://github.com/brainelectronics/changelog-from-snippets) action.\n\n##### Custom workflow\n\n```yaml\n---\nname: Generate changelog\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  changelog:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n        with:\n          # all history is needed to crawl it properly\n          fetch-depth: 0\n      - name: Set up Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: '3.11'\n      - name: Install\n        run: |\n          pip install snippets2changelog\n      - name: Update changelog with snippets\n        run: |\n          changelog-generator \\\n            changelog changelog.md \\\n            --snippets=.snippets \\\n            --in-place \\\n            --no-internal\n```\n\n#### Other\n\n```bash\npip install snippets2changelog\nchangelog-generator \\\n  changelog changelog.md \\\n  --snippets=.snippets \\\n  --in-place \\\n  --no-internal\n```\n\n## Contributing\n\n### Setup\n\nFor active development you need to have `poetry` and `pre-commit` installed\n\n```bash\npython3 -m pip install --upgrade --user poetry pre-commit\ngit clone https://github.com/brainelectronics/snippets2changelog.git\ncd snippets2changelog\npre-commit install\npoetry install\n```\n\n### Testing\n\n```bash\n# run all tests\npoetry run coverage run -m pytest -v\n\n# run only one specific tests\npoetry run coverage run -m pytest -v -k \"test_read_save_json\"\n```\n\nGenerate the coverage files with\n\n```bash\npython create_report_dirs.py\ncoverage html\n```\n\nThe coverage report is placed at `reports/coverage/html/index.html`\n\n### Changelog\n\nThe changelog format is based on [Keep a Changelog][ref-keep-a-changelog], and\nthis project adheres to [Semantic Versioning][ref-semantic-versioning].\n\nPlease add a changelog snippet, see above, for every PR you contribute. The\nchanges are categorised into:\n\n- `bugfixes` fix an issue which can be used out of the box without any further\nchanges required by the user. Be aware that in some cases bugfixes can be\nbreaking changes.\n- `features` is used to indicate a backwards compatible change providing\nimproved or extended functionalitiy. This does, as `bugfixes`, in any case\nnot require any changes by the user to keep the system running after upgrading.\n- `breaking` creates a breaking, non backwards compatible change which\nrequires the user to perform additional tasks, adopt his currently running\ncode or in general can't be used as is anymore.\n\nThe scope of a change shall either be:\n- `internal` if no new deployment is required for this change, like updates in\nthe documentation for example\n- `external` or `all` if this change affects the public API of this package or\nrequires a new tag and deployment for any other reason\n\nThe changelog entry shall be short but meaningful and can of course contain\nlinks and references to other issues or PRs. New lines are only allowed for a\nnew bulletpoint entry. Usage examples or other code snippets should be placed\nin the code documentation, README or the docs folder.\n\n## Credits\n\nA big thank you to the creators and maintainers of [SemVer.org][ref-semver]\nfor their documentation and [regex example][ref-semver-regex-example]\n\n\u003c!-- Links --\u003e\n[ref-keep-a-changelog]: https://keepachangelog.com/en/1.0.0/\n[ref-semantic-versioning]: https://semver.org/spec/v2.0.0.html\n[ref-semver]: https://semver.org/\n[ref-semver-regex-example]: https://regex101.com/r/Ly7O1x/3/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainelectronics%2Fsnippets2changelog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrainelectronics%2Fsnippets2changelog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainelectronics%2Fsnippets2changelog/lists"}