{"id":16432591,"url":"https://github.com/atufkas/progress-keeper","last_synced_at":"2025-04-04T16:19:53.057Z","repository":{"id":144933345,"uuid":"118749636","full_name":"atufkas/progress-keeper","owner":"atufkas","description":"Track, transform and present change log entries.","archived":false,"fork":false,"pushed_at":"2018-05-08T16:25:57.000Z","size":653,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-10T01:44:52.452Z","etag":null,"topics":["audiences","changelog","changelog-generator","commitizen","commits","conventional-changelog","conventional-commits","release-log"],"latest_commit_sha":null,"homepage":null,"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/atufkas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.html","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":"2018-01-24T10:26:10.000Z","updated_at":"2024-11-22T08:26:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"4c54ad37-06bf-47b2-b87f-aad94cc6ced4","html_url":"https://github.com/atufkas/progress-keeper","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atufkas%2Fprogress-keeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atufkas%2Fprogress-keeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atufkas%2Fprogress-keeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atufkas%2Fprogress-keeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atufkas","download_url":"https://codeload.github.com/atufkas/progress-keeper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208371,"owners_count":20901570,"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":["audiences","changelog","changelog-generator","commitizen","commits","conventional-changelog","conventional-commits","release-log"],"created_at":"2024-10-11T08:43:50.025Z","updated_at":"2025-04-04T16:19:53.035Z","avatar_url":"https://github.com/atufkas.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# progress-keeper\n\n[![Build Status](https://travis-ci.org/atufkas/progress-keeper.svg?branch=master)](https://travis-ci.org/atufkas/progress-keeper)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\nTrack, transform and present changelog entries.\n\n+++ **Note**: This project is in the state of an early stage\nconcept and under active development. API may change frequently. Feel free\nto ask, comment and contribute, I'd be happy to receive help and support!  +++\n\n\n## Introduction\n\nThis project aims to address the problem of generating user as well as\ndeveloper friendly changelog catalogues supporting various formats,\ngenerated from various sources. One major goal is to **aggregate and\npresent structured change log information based on relevance for a\nspecific audience**. The implementation and specification of formats\nfollows some best practices, recommendations and proposals like the\n[Conventional Commits Specification](https://conventionalcommits.org/).\n\n\n## Installation\n\nThis is a PHP 5.6+ / 7.0+ composer based project. A composer.phar archive bundle is included.\n\nClone project\n\n    $ git clone https://github.com/atufkas/progress-keeper\n    $ cd progress-keeper\n    \nInstall dependencies\n    \n    $ php ./composer.phar install\n\n\n## Running tests\n    \n    $ php ./composer.phar test      # Run tests by either calling composer defined script\n    $ ./vendor/bin/phpunit          # ...or just calling phpunit directly.\n\n\n## Examples \n\n### CLI\n\nprogress-keeper comes with a very simple CLI script that allows for converting a supported changelog source \nto a supported target format. Call it without arguments to receive a short help text:\n\n    $ ./bin/progress-keeper\n    \nFor testing a conversion of the project changelog (stored as JSON), you may run the following commands \n(results are written to stdout):\n\n    $ ./bin/progress-keeper ./pk-changelog.json json markdown\n    $ ./bin/progress-keeper ./pk-changelog.json json html\n\n\n### API\n\nThere are a few factory methods for giving quick access to the most common use cases. For parsing a changelog \nsource into the internal object representation just do something like this:\n        \n        use atufkas\\ProgressKeeper\\ProgressKeeperFactory;\n\n        $releaseLogFile = __DIR__ . '/my-changelog.json';\n        $changelog = ProgressKeeperFactory::getChangelog($releaseLogFile, 'json', ['*'], true);\n\n\nHave a look on that the 2nd parameter which is passed as an array containing just single element, a string with an \nasterisk ('*'): With this array you define to which audiences the selected log entries should be filtered down, \nwhere an asterisk has the meaning of \"all audiences\". If you just want to parse entries targeting the audience \"user\", \nthe line should be modified to:\n\n        $changelog = ProgressKeeperFactory::getChangelog($releaseLogFile, 'json', ['user'], true);\n\nYehaa, now play around and debug or dump output to see what the internal object structure looks like and how release and \nlog entry data can be accessed:\n\n        $latestRelease = $changelog-\u003egetLatestRelease();                    // Get latest release object\n        $currentVersion = $latestRelease-\u003egetVersionString();               // Get version string of a release\n        $logEntries = $currentVersion-\u003egetLogEntries();                     // Get all log entries of a release\n        $bugfixLogEntries = $currentVersion-\u003egetLogEntriesByType('fix');    // Get all log entries of type \"bugfix\"\n\nYou may now do whatever you want with the changelog data or use one of the writer (presenter) plugins to \nprogrammatically generate a changelog in a specific format, e.g. HTML:\n\n        use atufkas\\ProgressKeeper\\Presenter;\n        \n        $htmlPresenter = new HtmlPresenter();\n        $htmlPresenter-\u003esetChangelog($changelog);\n        $changelogHtml = $htmlPresenter-\u003egetOutput();\n        \nSame thing could be achieved by another factory method in one step:\n\n        $changelogHtml = ProgressKeeperFactory::getConvertedChangelog($releaseLogFile, 'json', 'html', ['user'], true);\n\nFor some more details on the concepts and available reader/presenter plugins see next section.\n\n\n\n## Concepts + API\n\nThe project is under active development. New features, concepts and\nbreaking changes are introduced frequently. Currently this library provides:\n\n- a definition for an \"intermediate JSON changelog format\" looking like this:\n    ``` json\n    {\n      \"name\": \"PK Sample-App\",\n      \"desc\": \"The app with forms that make you happy!\",\n      \"releases\": [\n        {\n          \"version\": \"1.0\",\n          \"date\": \"2018-01-30 12:12\",\n          \"remarks\": \"Now our app is ready for production.\",\n          \"changelog\": [\n            {\n              \"date\": \"2018-01-26\",\n              \"type\": \"feat\",\n              \"desc\": \"Added a batch mode for editing multiple records at once.\",\n              \"audience\": \"*\"\n            },\n            {\n              \"date\": \"2018-01-17\",\n              \"type\": \"fix(ui)\",\n              \"desc\": \"Validation failed when whitespace was transmitted via form value.\",\n              \"audience\": \"*\"\n            },\n            {\n              \"date\": \"2018-01-17\",\n              \"type\": \"chore\",\n              \"scope\": \"ci\",\n              \"desc\": \"Added support for Travis CI.\",\n              \"audience\": \"dev\"\n            }\n          ]\n        },\n        {\n          \"version\": \"0.2.0\",\n          \"date\": \"2018-01-24 17:30\",\n          \"remarks\": \"This version introduces this release log, updates internal dependencies and adds support for docker.\",\n          \"changelog\": [\n            {\n              \"date\": \"2018-01-23\",\n              \"type\": \"code\",\n              \"desc\": \"Set platform dependency to PHP \u003e= 5.6.0.\",\n              \"audience\": \"dev\"\n            }\n          ]\n        }\n      ]\n    }\n    ```\n\n\n- a **changelog model** that reflects a structure of the form: Changelog\n-\u003e Releases -\u003e Log Entries\n    - `atufkas\\ProgressKeeper\\Changelog`\n    - `atufkas\\ProgressKeeper\\Release\\Release`\n    - `atufkas\\ProgressKeeper\\LogEntry\\LogEntry`\n\n- a **source format reader interface** with implementations for:\n    - JSON: `atufkas\\ProgressKeeper\\Reader\\JsonReader`\n    - Markdown: `atufkas\\ProgressKeeper\\Reader\\MarkdownReader`\n\n- a **target format presenter interface** with implementations for:\n     - HTML: `atufkas\\ProgressKeeper\\Presenter\\HtmlPresenter`\n     - Markdown: `atufkas\\ProgressKeeper\\Presenter\\MarkdownPresenter`\n\n- **simple factory methods** allowing for generating a changelog from a given source file and source format\n    - as internal Changelog PHP object: `atufkas\\ProgressKeeperKeeperFactory::getChangelog`\n    - in target presentation format (by passing target format as additional argument): `atufkas\\ProgressKeeperKeeperFactory::getConvertedChangelog`\n\n- a **very basic CLI command** `./bin/progress-keeper` passing command line arguments to\n    - `atufkas\\ProgressKeeperKeeperFactory::getConvertedChangelog`\n\n\n\n## Contributing\n\nNo big deal, go ahead! Just follow current (PHP) coding standards and of course\nwrite tests. Feel free to improve or critzize existing code or ideas, ask if\nunsure about something or just generate an issue or pull request.\nI'll to my best to review them as soon as possible.\n\nWhen adding a feature or making a change, use progress-keeper to generate\nown changelogs by adding a log entry to `./pk-changelog.json` and generate\nnew Markdows and HTML versions of the whole changelog by running:\n\n    $ php ./composer.phar pre-commit\n\n    \n## Related to + heavily inspired by\n\n* [keep a changelog](https://github.com/olivierlacan/keep-a-changelog) - If you build software, keep a changelog.\n* [Conventional Commits Specification](https://conventionalcommits.org/)\n* [Angular: \"Commit Message Guidelines\"](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit)\n* [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) - Generate a changelog from git metadata\n* [commitizen](https://github.com/commitizen/cz-cli) - Simple commit conventions for internet citizens\n* [commitlint](https://github.com/marionebl/commitlint) - Lint commit messages\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatufkas%2Fprogress-keeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatufkas%2Fprogress-keeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatufkas%2Fprogress-keeper/lists"}