{"id":19765714,"url":"https://github.com/openhft/chronicle-release-notes","last_synced_at":"2025-02-28T03:46:44.830Z","repository":{"id":40258803,"uuid":"314276975","full_name":"OpenHFT/Chronicle-Release-Notes","owner":"OpenHFT","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-06T19:42:14.000Z","size":227,"stargazers_count":0,"open_issues_count":4,"forks_count":1,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-01-11T00:12:46.105Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenHFT.png","metadata":{"files":{"readme":"README.adoc","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":"2020-11-19T14:43:11.000Z","updated_at":"2022-06-01T13:09:46.000Z","dependencies_parsed_at":"2025-01-11T00:12:35.472Z","dependency_job_id":"25c19277-f5d5-4e1a-82d8-6019f80fe146","html_url":"https://github.com/OpenHFT/Chronicle-Release-Notes","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenHFT%2FChronicle-Release-Notes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenHFT%2FChronicle-Release-Notes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenHFT%2FChronicle-Release-Notes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenHFT%2FChronicle-Release-Notes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenHFT","download_url":"https://codeload.github.com/OpenHFT/Chronicle-Release-Notes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241096361,"owners_count":19908969,"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-12T04:19:11.716Z","updated_at":"2025-02-28T03:46:44.808Z","avatar_url":"https://github.com/OpenHFT.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Chronicle Release Notes\n\nimage:https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-release-notes-connector-api/badge.svg[link=\"https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-release-notes-connector-api\"]\n\nChronicle Release Notes is a library and CLI utility designed to automate the generation of release notes for GitHub repositories.\n\n== Motivation\n\nChronicle Release Notes was developed to mitigate the shortcomings of link:https://www.npmjs.com/package/gren-release-notes[gren] when working in a branched out multi-release environment.\n\nimage:images/release-diagram-1.png[]\n\nThe scenario depicted in the diagram above is quite difficult to handle using gren due to GitHub issues being branch-agnostic.\n\nWe're going to assume that each change depicted in the diagram above is associated with an issue. Once a release is performed, all issues closed between the last release, and the current one should be included in the release notes for our new release.\n\nAs an example, lets say that after making _Change #1_ we've release version 1.0.0 and after _Change #2_ we've release version 1.1.0. Any issues that were closed before the 1.0.0 release should be included in the release notes for 1.0.0.\n\nSimilarly, any issues that were closed before the 1.1.0 release should be included in the release notes for 1.1.0, but only the issues that were closed after the 1.0.0 release.\n\nThis is possible to do with gren quite easily, however let's take a look at an example where we have to branch out from our main release branch.\n\nLet's say after we've released version 1.1.0, we need to make additional changes to version 1.0.0. To do that, we would create a branch from the 1.0.0 release and make our changes there. These additional changes are represented by _Change #3_ in the diagram above and were chronologically made after _Change #2_.\n\nIf we were to release version 1.0.1 after making _Change #3_ and generate release notes using gren, the release notes would include all issues closed between versions 1.0.0 and 1.0.1. However, due to GitHub issues being branch-agnostic, the release notes would also include all issues created between 1.0.0 and 1.1.0 because of the overlapping timelines.\n\n== Installation Requirements\n\nBefore using the Chronicle Release Notes, make sure you have the following installed on your system:\n\n- link:https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html[Java 8]\n- link:https://maven.apache.org/[Maven]/link:https://gradle.org/[Gradle]\n\n== Installation\n\nMaven:\n\n[source,xml]\n----\n\u003cdependencies\u003e\n    ...\n    \u003cdependency\u003e\n        \u003cgroupId\u003enet.openhft\u003c/groupId\u003e\n        \u003cartifactId\u003echronicle-release-notes-connector-all\u003c/artifactId\u003e\n        \u003cversion\u003e${chronicle-release-notes.version}\u003c/version\u003e\n    \u003c/dependency\u003e\n    ...\n\u003c/dependencies\u003e\n----\n\nGradle:\n\n[source,groovy]\n----\ndependencies {\n    ...\n    implementation \"net.openhft:chronicle-release-notes-connector-all:${chronicle-release-notes.version}\"\n    ...\n}\n----\n\n== Connecting to GitHub\n\nBefore a release can be created, we must first gain access to GitHub's API. That can be done using the following code:\n\n[source,java]\n----\nfinal ConnectorProvider\u003cReleaseConnector\u003e releaseConnectorProvider = ConnectorProviderFactory.getInstance()\n    .getReleaseConnectorProvider(ConnectorProviderKeys.GITHUB)\n    .orElseThrow(() -\u003e new RuntimeException(\"Failed to find GitHub release provider\"));\n\nfinal ReleaseConnector releaseConnector = releaseConnectorProvider.connect(\"YOUR_PERSONAL_ACCESS_TOKEN\")\n    .orElseThrow(() -\u003e new RuntimeException(\"Failed to connect to GitHub\"));\n----\n\n== Creating a release\n\nWith Chronicle Release Notes, users are able to create releases from 2 sources - branches and milestones:\n\n=== Creating a release from a branch source\n\n[source,java]\n----\nfinal ReleaseResult releaseResult = releaseConnector.createReleaseFromBranch(\"owner/repository\", \"1.0.0\", \"master\");\n\nreleaseResult.throwIfFail();\n----\n\nIf release notes are created from a branch source, all issues that should be included in the generated release notes must be referenced through commit messages. For example:\n\n\n----\nCommit message\n\nCloses #1\n----\n\nIf this commit was made between the last release and the current one, then the issue with id 1 will be included in the generated release notes.\n\n=== Creating a release from a milestone source\n\n[source,java]\n----\nfinal ReleaseResult = releaseConnector.createReleaseFromMilestone(\"owner/respository\", \"1.0.0\", \"milestone1\");\n\nreleaseResult.throwIfFail();\n----\n\nIf release notes are created from a milestone source, all issues that should be included in the generated release notes must be included in the referenced milestone.\n\n== Additional release options\n\nWhen generating release notes, we're able to customize the generation process in a couple of ways with various options.\n\nFor branch releases, we have the following options:\n\n[source, java]\n----\n/**\n* Ignores all issues that have any of the specified labels\n*/\nignoreLabels(String... labels)\n\n/**\n* If true, then a release is overriden if it already exists. Otherwise, an exception is thrown.\n*/\noverrideRelease(boolean overrideRelease)\n\n/**\n* If true, then any referenced issue will be included in the generated release notes. Otherwise, an issue reference needs to be preceeded by a closing keyword.\n*/\nincludeIssuesWithoutClosingKeyword(boolean include)\n\n/**\n* If true, then any referenced pull request will be included in the generated release notes alongside issues. Otherwise, pull requests are not allowed (default).\n*/\nincludePullRequests(boolean include)\n----\n\nThese options can be modified via `BranchReleaseOptions::Builder`:\n\n[source, java]\n----\nfinal BranchReleaseOptions releaseOptions = new BranchReleaseOptions.Builder()\n    .ignoreLabels(\"wontfix\")\n    .overrideRelease(true)\n    .includeIssuesWithoutClosingKeyword(true)\n    .includePullRequests(false)\n    .build();\n\nfinal ReleaseResult releaseResult = releaseConnector.createReleaseFromBranch(\"owner/repository\", \"1.0.0\", \"master\", releaseOptions);\n\nreleaseResult.throwIfFail();\n----\n\nFor milestone releases, we have the following options:\n\n[source, java]\n----\n/**\n* Ignores all issues that have any of the specified labels\n*/\nignoreLabels(String... labels)\n\n/**\n* If true, then a release is overriden if it already exists. Otherwise, an exception is thrown.\n*/\noverrideRelease(boolean overrideRelease)\n----\n\nThese options can be modified via `MilestoneReleaseOptions::Builder`:\n\n[source, java]\n----\nfinal MilestoneReleaseOptions releaseOptions = new MilestoneReleaseOptions.Builder()\n    .ignoreLabels(\"wontfix\")\n    .overrideRelease(true)\n    .build();\n\nfinal ReleaseResult releaseResult = releaseConnector.createReleaseFromMilestone(\"owner/repository\", \"1.0.0\", \"milestone1\", releaseOptions);\n\nreleaseResult.throwIfFail();\n----\n\n== Providing additional context\n\nSometimes an issue name might not be descriptive enough to provide enough context to the user reading the release notes. When creating a release, users are able to append additional information to specific issues in form of comments.\n\nTo add more information to a specific issue, add a comment to the specific issue in the following format:\n\n[source, markdown]\n----\n#comment A comment that provides additional information to the user\n----\n\nUsers may write multiple comments of this format, but only the latest comment will be included in the release notes.\n\nWARNING: Be cautious when using this feature on open source repositories. There are no checks in place to verify which users are allowed to write these comments.\n\nThis option is disabled by default. To enable it, add the following line to your release options:\n\n[source, java]\n----\n.includeAdditionalContext(true)\n----\n\n== GraphQL Usage\n\nChronicle Release Notes uses GitHub's REST API v3 to obtain *most* of the required information needed to generate release notes for a particular release. During the release note generation process, at a certain point we are required to fetch the project tags in a chronological order.\n\nFetching tags for a project is easily obtainable with the V3 API, however, returning them in a chronological order is impossible. A potential solution is sorting the tags in the JVM once they're returned, but this introduces a rate limit violation. All details about a certain tag are stored in a separate resource, which means if we want to get these details, we have to execute an additional request for every tag we pulled.\n\nFor small projects this is not a problem, but for more advanced release pipelines during which multiple projects with hundreds of tags are released, this can cause unnecessary delays between releases.\n\nTo avoid this issue all together, this particular part of the release note generation process is done via the GraphQL v4 API. The v4 API allows us to sort the fetched tags via the executed GraphQL query, which means we are able to return the tags in a chronological order in 1 request (instead of N^2 requests).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenhft%2Fchronicle-release-notes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenhft%2Fchronicle-release-notes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenhft%2Fchronicle-release-notes/lists"}