{"id":28335049,"url":"https://github.com/mridang/semantic-release-peer-version","last_synced_at":"2026-03-11T13:15:48.316Z","repository":{"id":292001957,"uuid":"966570761","full_name":"mridang/semantic-release-peer-version","owner":"mridang","description":"A semantic-release plugin to prevent a new major version release if a specified upstream GitHub repository does not have a matching or higher major version SemVer tag on a given branch.","archived":false,"fork":false,"pushed_at":"2026-01-12T03:27:46.000Z","size":500,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-12T10:21:58.965Z","etag":null,"topics":["release-automation","semantic-release","semantic-release-plugin"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@mridang/semantic-release-peer-version","language":"TypeScript","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/mridang.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-15T06:05:09.000Z","updated_at":"2026-01-09T05:59:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"260caa55-25f1-4360-9ad2-8a7751876821","html_url":"https://github.com/mridang/semantic-release-peer-version","commit_stats":null,"previous_names":["mridang/semantic-release","mridang/semantic-release-peer-version"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/mridang/semantic-release-peer-version","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fsemantic-release-peer-version","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fsemantic-release-peer-version/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fsemantic-release-peer-version/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fsemantic-release-peer-version/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mridang","download_url":"https://codeload.github.com/mridang/semantic-release-peer-version/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mridang%2Fsemantic-release-peer-version/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30382642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T12:49:11.341Z","status":"ssl_error","status_checked_at":"2026-03-11T12:46:41.342Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["release-automation","semantic-release","semantic-release-plugin"],"created_at":"2025-05-26T21:55:06.055Z","updated_at":"2026-03-11T13:15:48.307Z","avatar_url":"https://github.com/mridang.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Semantic Release - Upstream Major Version Blocker\n\nA [semantic-release](https://github.com/semantic-release/semantic-release)\nplugin to prevent a new major version release if a specified upstream GitHub\nrepository does not have a matching or higher major version SemVer tag on a\ngiven branch.\n\nThis plugin helps ensure that your project's major versions do not prematurely\nget ahead of a critical upstream dependency, maintaining versioning harmony and\npreventing accidental releases of software that may rely on unreleased\nupstream features.\n\n### Why?\n\nWhen your project (e.g., a client library, a microservice component) has a\ncritical upstream dependency, its major version changes are often closely\ntied to the major versions of that dependency. For instance, you might be\ndeveloping `your-project v2.1.0` which is compatible with\n`upstream-dependency v2.x.x`. If `your-project` is due for a major update\nto `v3.0.0`, this new version is likely intended to align with, or require\nfeatures from, `upstream-dependency v3.0.0` (or newer).\n\nReleasing `your-project v3.0.0` _before_ `upstream-dependency` has itself\nreached at least major version 3 (e.g., `v3.0.0`) on its relevant branch\ncan lead to several problems:\n\n- **Integration Issues:** Your new `v3.0.0` might be incompatible with the\n  currently deployed `v2.x.x` of the upstream service because it expects\n  features or breaking changes from the (as yet unreleased) upstream\n  `v3.0.0`.\n- **User Confusion:** Users might upgrade `your-project` to `v3.0.0` expecting\n  it to work with the latest stable version of the upstream dependency,\n  only to discover it's designed for a future, unreleased upstream\n  version.\n- **Deployment Blockers:** You might intend for `your-project v3.0.0` to be\n  released in tandem with `upstream-dependency v3.0.0`. However, if your\n  project's release pipeline triggers first, your `v3.0.0` could be\n  published prematurely, leading to a version that doesn't work\n  correctly in the current ecosystem.\n\nThis plugin provides a safeguard by checking a designated upstream GitHub\nrepository and a specific branch within it. If your automated release process\n(via semantic-release) determines that a major version bump is due for your\nproject, this plugin will first verify that the upstream dependency has\nalready published a release tag indicating that major version (or a higher\none) on its specified branch. If this condition is not met, the release of\nyour project is blocked, preventing these potential issues.\n\n## Installation\n\nInstall using NPM by using the following command:\n\n```sh\nnpm install --save @mridang/semantic-release-peer-version\n```\n\n## Usage\n\nTo use this plugin, add it to your semantic-release configuration file (e.g.,\n`.releaserc.js`, `release.config.js`, or in your `package.json`).\n\nThe plugin should typically be placed _before_ the `@semantic-release/npm` or\n`@semantic-release/github` plugins in the `plugins` array, as it needs to run\nits checks in the `verifyConditions` and `analyzeCommits` steps.\n\n**Example Configuration (`.releaserc.js`):**\n\n```javascript\nmodule.exports = {\n  branches: ['main', 'next'],\n  plugins: [\n    '@semantic-release/commit-analyzer', // Must come first to determine release type\n    [\n      '@mridang/semantic-release-peer-version',\n      {\n        repo: 'owner/repo',\n        // Optional: GitHub token for private repos or to avoid rate limiting\n        // Defaults to process.env.GITHUB_TOKEN || process.env.GH_TOKEN\n        // githubToken: process.env.UPSTREAM_GITHUB_TOKEN\n      },\n    ],\n    '@semantic-release/release-notes-generator',\n    '@semantic-release/changelog',\n    '@semantic-release/npm', // If publishing to npm\n    '@semantic-release/github', // For creating GitHub releases and comments\n    '@semantic-release/git', // To commit package.json, CHANGELOG.md, etc.\n  ],\n};\n```\n\n## Known Issues\n\n- **GitHub API Rate Limiting:** The plugin interacts with the GitHub API to\n  fetch release information (which includes tags) and potentially compare\n  commits. Unauthenticated API requests are subject to stricter rate limits.\n  To prevent disruptions, especially in CI environments or with frequent\n  usage, providing a `githubToken` is highly recommended. This enables the\n  more lenient rate limits associated with authenticated requests.\n- **Upstream Repository Tagging and Versioning:** This plugin relies on the\n  upstream repository adhering to [Semantic Versioning](https://semver.org/)\n  for its release tags. These SemVer tags should be associated with\n  published releases on the repository. If the upstream repository does not\n  consistently use SemVer for its release tags, the plugin may be unable to\n  accurately determine versioning information, such as a major version cap.\n- **Release Pagination:** The plugin currently fetches data for up to the 100\n  most recent releases from the upstream repository to identify relevant\n  SemVer tags. If the specific SemVer-tagged release crucial for the\n  plugin's logic (e.g., for version capping or comparison) is older than\n  these 100 most recent releases, it might not be detected.\n- **Token Permissions:** When a `githubToken` is provided, it must have\n  sufficient permissions to access the upstream repository's data. For\n  private repositories, the `repo` scope (granting full control of private\n  repositories) is typically required. For public repositories, while a token\n  might not be strictly necessary for basic read access, providing one for\n  authenticated requests (which helps with rate limits) means the token\n  must still have adequate permissions to read repository content, list\n  releases, and compare commits if these operations are performed by the\n  plugin.\n\n## Useful links\n\n- **[Semantic Release](https://github.com/semantic-release/semantic-release):**\n  The core automated version management and package publishing tool.\n- **[Semantic Versioning (SemVer)](https://semver.org/):** The versioning\n  specification that semantic-release adheres to.\n\n## Contributing\n\nIf you have suggestions for how this app could be improved, or\nwant to report a bug, open an issue - we'd love all and any\ncontributions.\n\n## License\n\nApache License 2.0 © 2024 Mridang Agarwalla\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmridang%2Fsemantic-release-peer-version","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmridang%2Fsemantic-release-peer-version","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmridang%2Fsemantic-release-peer-version/lists"}