{"id":25317870,"url":"https://github.com/vaimo/composer-changelogs","last_synced_at":"2025-10-28T21:30:55.886Z","repository":{"id":62543720,"uuid":"143271201","full_name":"vaimo/composer-changelogs","owner":"vaimo","description":"Provide information about package changes based on change-log files that are bundled with releases; provide tools for generating documentation files from change-log JSON sources","archived":false,"fork":false,"pushed_at":"2024-02-08T10:00:01.000Z","size":416,"stargazers_count":10,"open_issues_count":6,"forks_count":2,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-01-21T14:49:20.421Z","etag":null,"topics":["changelog","composer-commands","composer-plugin","generator"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vaimo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE_VAIMO.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":"2018-08-02T09:14:54.000Z","updated_at":"2022-12-21T09:26:16.000Z","dependencies_parsed_at":"2024-02-08T10:50:15.894Z","dependency_job_id":null,"html_url":"https://github.com/vaimo/composer-changelogs","commit_stats":{"total_commits":157,"total_committers":5,"mean_commits":31.4,"dds":"0.20382165605095537","last_synced_commit":"cfe6fafad10338899ea47870f4a4ff654f6a3928"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaimo%2Fcomposer-changelogs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaimo%2Fcomposer-changelogs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaimo%2Fcomposer-changelogs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaimo%2Fcomposer-changelogs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vaimo","download_url":"https://codeload.github.com/vaimo/composer-changelogs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238725864,"owners_count":19520115,"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":["changelog","composer-commands","composer-plugin","generator"],"created_at":"2025-02-13T19:55:21.991Z","updated_at":"2025-10-28T21:30:55.426Z","avatar_url":"https://github.com/vaimo.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vaimo Composer Changelogs\n\n[![Latest Stable Version](https://poser.pugx.org/vaimo/composer-changelogs/v/stable)](https://packagist.org/packages/vaimo/composer-changelogs)\n[![Build Status](https://travis-ci.org/vaimo/composer-changelogs.svg?branch=master)](https://travis-ci.org/vaimo/composer-changelogs)\n[![Total Downloads](https://poser.pugx.org/vaimo/composer-changelogs/downloads)](https://packagist.org/packages/vaimo/composer-changelogs)\n[![Daily Downloads](https://poser.pugx.org/vaimo/composer-changelogs/d/daily)](https://packagist.org/packages/vaimo/composer-changelogs)\n[![Minimum PHP Version](https://img.shields.io/packagist/php-v/vaimo/composer-changelogs.svg)](https://php.net/)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/vaimo/composer-changelogs/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/vaimo/composer-changelogs/?branch=master)\n[![Code Climate](https://codeclimate.com/github/vaimo/composer-changelogs/badges/gpa.svg)](https://codeclimate.com/github/vaimo/composer-changelogs)\n[![License](https://poser.pugx.org/vaimo/composer-changelogs/license)](https://packagist.org/packages/vaimo/composer-changelogs)\n\nProvides information about package changes based on changelog files that are bundled with releases and introduces tools/commands for generating documentation files (in many different formats and with the option to create custom templates) from changelog sources. \n\nIt comes with several commands that aid the developer on setting up automatic package publishing logic in CI.\n\nMore information on recent changes [HERE](./CHANGELOG.md) (which also serves as an example of how MD formatting for changelog.json looks like).\n\nNote that the changelog output will only be generated when you have configured output generators for any of the output formats.\n\n## Configuration: overview\n\nEnvironment variables can be defined as key value pairs in the project's composer.json\n\n```json\n{\n  \"extra\": {\n    \"changelog\": {\n      \"source\": \"changelog.json\"\n    }\n  }\n}\n```\n\n## Configuration: changelog file format\n\nThe module expects certain conventions to be used when declaring new changelog records, which are based\non grouping the changes based on semantic versioning rules (+ provides some extra ones for even greater \ndetail): breaking, feature, fix (extras: overview, maintenance). \n\nThe extra keys are mostly meant for dumping some data into the release notes about general theme of the \nnew release or allowing some extra details to be added for the developers.\n\n```json\n{\n    \"1.0.0\": {\n        \"overview\": \"Some general overarching description about this release; Can be declared as a list\",\n        \"breaking\": [\n            \"code: Something changed in the sourcecode\",\n            \"data: Something changed about the data format\",\n            \"schema: Something changed about the database\",\n            \"config: config path or flag renamed\",\n            \"logic: default/expected execution path of the application/module changed\"\n        ],\n        \"feature\": [\n            \"short description about feature1\",\n            \"short description about feature2\"\n        ],\n        \"fix\": [\n            \"short description about fix1\",\n            \"short description about fix2\"\n        ],\n        \"maintenance\": [\n            \"short description about changing something about the architecture, etc\"\n        ],\n        \"branch\": \"useful for multiple major-release branches and using 'version' and 'info' commands\"\n    }\n}\n```\n\nNote that all the groups are optional - the documentation generation and other features of the plugin \nwill not error out when they're missing.\n\nDeveloper is not limited only to these groups and any other group will end up being used in documentation \ngenerator output as well. The exception to this rule is the \"overview\" group, which is bound to additional\nprocessing logic and is not perceived as a \"changes\" group in the code. \n\n## Configuration: adding releases\n\nThe releases should be added in ascending order where the latest release is always the topmost record (as \nis the case with all change-logs that one might encounter).\n\n```json\n{\n    \"2.0.0\": {},\n    \"1.2.1\": {},\n    \"1.1.1\": {},\n    \"1.1.0\": {},\n    \"1.0.0\": {}\n}\n``` \n\n## Configuration: upcoming releases\n\nTo make sure that all the commands of the plugin work as intended, upcoming releases should be marked in\nthe changelog as \"DEV.1.2.3\", which will cause latest version reporter command to skip over it. Same could be\nachieved if the values is left blank.\n\nThis is useful in situations where multiple people are working on the upcoming release and you want to \npostpone the release of that version (in case you have some CI logic build around the changelog version command). \nAs long as the 'DEV.' is there, the developers can stack their changes together under the same changelog record.\n\n```json\n{\n    \"DEV.1.2.3\": {\n        \"feature\": [\n            \"some upcoming, yet to be released feature\"\n        ]\n    }\n}\n```\n \nThe plugin uses composer constraints validator so anything that does not validate as version constraint\nwill be skipped over.\n\n## Feature: comments in changelog\n\nUseful in situations when there's a specific guideline within a team on how changelog should be maintained and \nfilled per release and what kind of groups should be used.\n\n```json\n{\n    \"_readme\": \"Make sure to follow the conventions: http://some.url/changelog-conventions.html\",\n    \"_guide\": \"Some tips on how the changelog for this specific package is maintained and updated\",\n    \"1.2.3\": {\n       \"feature\": [\n           \"some feature\"\n       ]\n    }\n}\n```\n\nNote that comments can be added on any level of the change-log and will always be ignored by the changelog \nreader/generator.\n\n## Feature: repository links\n\nThe changelog generator is capable of adding repository links to the changelog for each version by \npresenting both source link for certain version as well as diff/comparison for the code when compared\nto previous release.\n\nThis activates on two situations:\n\n* When composer.json of the package has support/source defined (part of standard Composer package config schema)\n* When repository with proper remote destination has been configured (with well formed URL)\n\nThe variables that become available through this in templates: {{link}}, {{diff}}.\n\nThis feature is enabled by default, but can be enabled by defining the following under changelog \nconfiguration within the composer.json of the package:\n\n```json\n{\n  \"extra\": {\n    \"changelog\": {\n      \"feature\": {\n        \"links\": false\n      }\n    }\n  }\n}\n```\n\nThe links can be disabled for a single generator run as well by overriding the URL configuration with a \nspecific command argument:\n\n```shell\ncomposer changelog:generate --url=false\n``` \n\n## Feature: release dates\n\nThe module will try to resolve the release date of certain version from the package \nrepository when it's available. The available options to be used in output templates \nare: {{date}}, {{time}}.\n\nThis feature is enabled by default, but can be enabled by defining the following under \nchangelog configuration within the composer.json of the package: \n\n```json\n{\n  \"extra\": {\n    \"changelog\": {\n      \"feature\": {\n        \"dates\": false\n      }\n    }\n  }\n}\n```\n\n## Output: generators\n\nThis example is based on making Sphinx documentation generation available.\n\n```json\n{\n  \"extra\": {\n    \"changelog\": {\n      \"source\": \"changelog.json\",\n      \"output\": {\n        \"sphinx\": \"docs/changelog.rst\"\n      }\n    }\n  }\n}\n```\n\nAvailable types: html, md, rst, slack, sphinx, txt, yml\n\n## Output: templates\n\nThe plugin ships with built-in templates for each of the generators, which can be configured by defining \ngenerators in an extended format.\n\n```json\n{\n  \"extra\": {\n    \"changelog\": {\n      \"source\": \"changelog.json\",\n      \"output\": {\n        \"sphinx\": {\n          \"path\": \"docs/changelog.rst\",\n          \"template\": \"my/template/path/template123.mustache\"\n        }\n      }\n    }\n  }\n}\n```\n\nNote that the template file path is relative to the package root that owns the changelog configuration.\n\nTemplates use Mustache syntax with some extra helpers (for which the built-in templates serve as \ndocumentation/examples).  \n\nWhen relying on the generators to produce the changelog documentation, make sure to add the output path to \nVCS ignore file as well to avoid producing unintended modifications. The file will be overwritten if exist \nin the repository before the documentation generation is called.\n\nThe generator does support Mustache partials as well in which case the template paths should be given as \ndictionary where the entry point template has been defined under the key \"root\".\n\n ```json\n {\n \n   \"template\": {\n     \"root\": \"my/template/path/custom_root.mustache\",\n     \"mypartial\": \"my/template/path/release.mustache\"\n   }\n }\n ```\n\nIn this example, the choice to define a template for the key \"mypartial\" derives directly from referring to\nsuch a Mustache partial in the template that's defined in \"root\". \n\nThe reserved names for partials in this plugin are:\n\n* root - main entry-point for the renderer\n* release - used by default to output certain changelog group/version and it's details AND by changelog:info\n\nThe base files for each template can be found from [HERE](https://github.com/vaimo/composer-changelogs/tree/master/views).\n\n## Commands\n\n```shell\n# Generate documentation pages from changelog configuration\ncomposer changelog:generate \n\n# Generate changelog with version-bound (src) and (diff) links for each release\n# Will override the default setting configured for the module\nchangelog:generate --url ssh://hg@bitbucket.org/some/repository\n\n# Report latest valid version from changelog (skip over the ones that are yet to be released)\ncomposer changelog:version\n\n# Report latest valid version for release/1.X\ncomposer changelog:version --branch release/1.X\n\n# Report latest release record from changelog (might be same as last valid)\ncomposer changelog:version --tip\n\n# Report upcoming release version from changelog (returns blank if there is no upcoming version)\ncomposer changelog:version --upcoming\n\n# Report current latest version without PATCH version\ncomposer changelog:version --segments 2\n\n# Report latest release details (in requested format)\ncomposer changelog:info\n\n# Validate changelog files content\ncomposer changelog:validate\n\n# Setup basic usage of the changelogs for a module\ncomposer changelog:bootstrap\n```\n\n## Upgrading The Module\n\nWhen upgrading the module, one might encounter odd crashes about classes not being found or class \nconstructor arguments being wrong. \n\nThis usually means that the class structure or constructor footprint in some of the classes have changed \nafter the upgrade which means that the plugin might be running with some classes from the old and some \nclasses from the new version. \n\nIt is safe to ignore errors like these when running the `composer update` command again does not produce \nany side-effects.\n\n## Development\n\nThe modules ships with a dedicated development branch [devbox](https://github.com/vaimo/composer-changelogs/tree/devbox) \nwhich contains configuration for spinning up a dedicated development environment that can be used together \nwith VSCode's [Remote Containers](https://code.visualstudio.com/docs/remote/containers).\n\nNote that there is no strict requirement to use such a setup, but it's what was used to author the plugin\nand if you want to be sure that you have everything up and running without hick-ups, you can just as well\ntake the shortcut.\n\nSystem requirements:\n\n1. Have Docker installed.\n1. Have VSCode installed with 'Remote - Containers' extension.\n1. Have Mutagen installed (used for selecting syncing).\n\nSetup:\n\n1. `git checkout devbox .devcontainer Dockerfile docker-compose.yml mutagen.yml`\n1. `git reset .devcontainer Dockerfile docker-compose.yml mutagen.yml`\n1. [open the project with VSCode that has Remote Container extension installed]\n1. [use the 'Reopen in Container' option that is given in a prompt that opens]\n1. (only on Windows) `mutagen project start`\n1. Use 'Terminal \u003e New Terminal' to open a terminal within the IDE.\n1. [from the terminal you can install the packages, trigger debugger, etc]\n\nNote this setup does come with a pre-bootstrapped xDebugger, you just have to use the Run menu \nin VSCode and start listening and trigger a command via the terminal.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaimo%2Fcomposer-changelogs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaimo%2Fcomposer-changelogs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaimo%2Fcomposer-changelogs/lists"}