{"id":15802017,"url":"https://github.com/jhechtf/version-bump","last_synced_at":"2025-03-31T21:59:57.608Z","repository":{"id":40431761,"uuid":"474851757","full_name":"jhechtf/version-bump","owner":"jhechtf","description":"A pluggable version bumping software (akin to standard-version) written in Deno + TS","archived":false,"fork":false,"pushed_at":"2024-04-13T19:52:01.000Z","size":141,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-14T09:55:10.704Z","etag":null,"topics":["changelog","deno","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jhechtf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-03-28T05:01:09.000Z","updated_at":"2024-04-19T07:41:32.296Z","dependencies_parsed_at":"2024-04-19T07:41:31.497Z","dependency_job_id":null,"html_url":"https://github.com/jhechtf/version-bump","commit_stats":{"total_commits":21,"total_committers":1,"mean_commits":21.0,"dds":0.0,"last_synced_commit":"d4b56794aeb6b991856c58d69d979d1c13f119b6"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhechtf%2Fversion-bump","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhechtf%2Fversion-bump/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhechtf%2Fversion-bump/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhechtf%2Fversion-bump/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhechtf","download_url":"https://codeload.github.com/jhechtf/version-bump/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246547387,"owners_count":20794970,"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","deno","typescript"],"created_at":"2024-10-05T01:41:40.369Z","updated_at":"2025-03-31T21:59:57.590Z","avatar_url":"https://github.com/jhechtf.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Version Bump\n\nWe bumpin' versions like it's 1999.\n\nInspiration for this project comes from\n[Standard Version](https://github.com/conventional-changelog/standard-version).\n\n## Version Bump 2.0\n\nVersion Bump has moved from TSyringe to Inversify. The move was done largely as\nan effort to enable Version Bump to run in versions of Deno that used TypeScript\n5+, which made some changes to decorators that broke TSyringe.\n\nFor Version Bump `\u003e=2.0.0` you will need to be on at least `deno\u003e=1.31.0`.\n\n## Notes\n\n**VERSION 0.2.0 IS BROKEN. DO _NOT_ USE**\n\nIf you are using a version of Deno that has TypeScript 5, you will need to use\nVersion Bump `\u003e=1.1.1`, OR run with the `--no-check` (not advised) option, e.g.:\n\n```\ndeno run -A --no-check https://deno.land/x/version_bump/cli.ts\n```\n\nThis is because TS 5 made some updates to decorators which changed the\ndefinitions for certain types of decorators.\n\n### Things to come\n\nNothing so far, but feel free to file a new\n[Issue](https://github.com/jhechtf/version-bump/issues) in the Github repo to\nrequest something\n\n## Installation and Usage\n\n### Configuration File\n\nIf you create a `.vbump.json` file in the same directory where you would run\n`version-bump`, then you can use it to hold configuration options so that you\ndon't have to pass in the information every time you run the CLI.\n\nThe values you can pass in the file are documented in the schema JSON noted\nbelow.\n\n```jsonc\n{\n  \"$schema\": \"https://deno.land/x/version_bump/schema/config.json\",\n  // Could also be set to a local file like \"./custom-preset\".\n  \"preset\": \"https://some-host.com/custom-preset.ts\"\n}\n```\n\n### As a task\n\nThe preferred way to use Version Bump would be to add a task definition to your\n`deno.json` file like so\n\n```json\n{\n  \"tasks\": {\n    \"version-bump\": \"deno run -A https://deno.land/x/version_bump@1.1.0/cli.ts\"\n  }\n}\n```\n\n#### In GitHub Actions\n\nCreate a workflow called `version.yml` in `.github/workflows` with the following\ncontents\n\n**NOTE 1:** Version Bump defaults to whoever the current Git user is. If your\nGithub branch has protection rules that require pull requests or signed commits,\nthis job _will_ fail. Work is being done to determine the best way to sign\ncommits through actions. See\n[#33](https://github.com/jhechtf/version-bump/issues/33) for information as it\ncomes.\n\n**NOTE 2:** When using `actions/checkout@v3` you must set a `fetch-depth` to `0`\nin order to get all the commit history. If your repository has many commits\nbetween version releases, this might cause an increase in run time and could\npossibly fail.\n\n```yml\nname: Version Bump\non:\n  push:\n    branches: [\"mainline\"]\n\npermissions:\n  contents: write\njobs:\n  bump:\n    name: Bump and Push\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n        with:\n          # Gotta set the fetch depth to 0 so that it fetches everything\n          fetch-depth: 0\n      - uses: denoland/setup-deno@v1\n      - run: git config user.name \"version-bot\" \u0026\u0026 git config user.email \"your-email+bot@gmail.com\"\n      - run: deno task version-bump\n      - run: git push \u0026\u0026 git push --tags\n```\n\n### Installation (not recommended)\n\nFor Deno `\u003c1.20`, you must install or run the script directly.\n\n```\ndeno install -A -n version-bump https://deno.land/x/version_bump/cli.ts\n# In the git directory you want to version bump\nversion-bump\n```\n\n#### Alternative\n\n```\ndeno run -A https://deno.land/x/version_bump/cli.ts\n```\n\n## Options\n\nCurrently we have the following command-line arguments you can pass.\n\n### --firstRelease\n\nAdding `--firstRelease` will not bump version, regardless of commits and will\ninstead release it as the version found by the strategy (default: `deno`, which\nlooks in your `deps.ts` file for an export named `VERSION`).\n\n### --preset\n\n**Default** `angular`\n\nThe preset is the engine that determines what the new version will be based on\nthe current version, the commits, and arguments passed to the CLI.\n\nTo make a custom implementation please see\n[Making a Git Convention](#making-a-git-convention)\n\n### --allowEmpty\n\n**Default** `false`.\n\nGenerally not recommended to use as it would allow for empty commits to occur.\n\n### --versionStrategy\n\n**Default** `deno`\n\nThe strategy to fetch version information. The default is `deno`, and the only\nother options currently bundled together is the `node` and `cargo` strategies.\nPlease see the table below for more information about these two items.\n\n| Preset        | Preset Value | Primary Version Source                               | Fallback                       |\n| ------------- | ------------ | ---------------------------------------------------- | ------------------------------ |\n| Deno (legacy) | `deno`       | `VERSION` export in root `deps.ts`                   | Most recent git tag or `0.1.0` |\n| Deno(Json)    | `deno-json`  | `\"version\"` key in `deno.json` or `deno.jsonc`       | ^                              |\n| Cargo         | `cargo`      | `version` key in `[package]` section of `Cargo.toml` | ^                              |\n| Node          | `node`       | `\"version\"` key in `package.json`                    | ^                              |\n| JSR           | `jsr`        | `\"version\"` key in `jsr.json`                        | ^                              |\n\nIn order to make a custom `VersionStrategy` please check the\n[Making a Version Strategy](#making-a-version-strategy)\n\n### --changelogWriter\n\n**Default** `default`\n\nThe changelog writer is the class responsible for putting the data in stored\ninto the commits into the CHANGELOG.md file.\n\nIn order pass a custom changelog writer you must extends the changelog writer\nclass and make sure to pass the `.ts` extension. E.g. if you have a changelog\nwriter at `src/custom.changelog.ts` you would reference it with\n\n```\nversion-bump --changelogWriter src/custom.changelog.ts\n```\n\nSee [Making a Changelog Writer](#making-a-changelog-writer) for how to code your\nown custom ChangelogWriter\n\n### --changelogPath\n\n**Default** `CHANGELOG.md`\n\nA string value representing the position of the CHANGELOG.md file in reference\nof the\n\u003cabbr title=\"Current Working Directory\"\u003eCWD\u003c/abbr\u003e.\n\n### --baseVersion\n\n**Default** `false`\n\nThe base version to use if no version can be found. Defaults to `false` to allow\nfor the users to send in a version that is not `0.1.0`.\n\n### --firstRelease\n\n**Default** `false`\n\nWhether or not this is the first release. This way no bumping of the\n`--baseVersion` is done.\n\n### --versionPrefix\n\n**Default** ``\n\nThe version prefix, used when writing tags. If a version is found that does not\nhave the version prefix, such as values that would occur in the `VERSION` export\nor the `version` key in a package.json file the value is prepended on to look\nfor the corresponding tags.\n\n### --hostUrl\n\nCurrently unused. Set it to whatever you want, it changes nothing!\n\n### --dryRun\n\n**Default** `false`\n\nWhether or not this is a dry run. Setting to `true` will disable writing the\nupdates to the files used by your VersionStrategy.\n\n### --historic\n\n**Default** `false`\n\nShould this be a _historic_ run? A historic run differs a bit between a regular\nrun in one main way:\n\n_Historic runs go through all commits, and attempt to use the current convention\nto build a CHANGELOG starting from the very beginning of the packages Git\nhistory_. Regular runs only work in the last batch of commits, and work to\nprogress the project one group of commits at a time.\n\nThis is a good flag to run if you are, say, moving from using one version prefix\nto another. For example, if you were originally using the `--versionPrefix`\nargument of `v`, but no longer wish to append `v` to your calculated version,\nrun this command with the version prefix you would like to use. It will not\nre-tag the old commits, but it will create a good CHANGELOG with appropriate\ndiff URLs.\n\n### --logLevel\n\n**Default** `ERROR`\n\nThis controls how much information you see about the inner workings of the\nVersion Bump CLI. The levels are as followed, with each level including the\nlevels below them:\n\n- DEBUG (most logging)\n- INFO\n- WARNING\n- ERROR\n- CRITICAL (least logging)\n\nPlease see [the documentation](https://deno.land/std@0.132.0/log/) about the\nDeno Logger for more thorough information about logging levels.\n\n## References\n\nThis section has the references for building custom implementation of the inner\nclasses that relate to Version Bump.\n\nPlease note that unless otherwise stated, in order to be picked up by the system\nthe exported class _must_ be the default export. E.g.\n\n```ts\n// ✅ Good\nexport default class CustomChangelogWriter extends ChangelogWriter {\n  // Rest of code\n}\n\n// ❌ Bad\nexport class CustomChangelogWriter extends ChangelogWriter {\n  // rest of code\n}\n```\n\n### Injectables\n\nThere are a few injectables that can be used in your code. These will have their\ngiven defaults, but will be determined at run-time for the CLI. They can be\nincluded by including them in the constructor in the case of classes, _OR_ by\nusing the `inject` decorator for certain tokens.\n\n#### Classes\n\nThese classes can be injected into your code by TSyringe so long as your class\nis correctly marked as `@injectable`.\n\n- `Git`\n\n#### Tokens\n\nThese tokens can be registered in via the `@inject` decorator on a constructor.\n\n|  Token   |       Type       | Example                                                                 |\n| :------: | :--------------: | :---------------------------------------------------------------------- |\n|  `cwd`   |     `string`     | `constructor(@inject('cwd') public readonly cwd: string) {}`            |\n|  `args`  |      `Args`      | `constructor(@inject('args) public readonly args: Args) {}`             |\n| `logger` | `LoggerInstance` | `constructor(@inject('logger') public readonly log: LoggerInstance) {}` |\n\n**NOTE** The `LoggerInstance` type is an inferred type from an import. Work is\nin process to determine how best to wrap it into something more cohesive with\nthe system, but for now it is fine to use as it adds level-based logging to the\napplication.\n\n### Making a Changelog Writer\n\nTo make a `ChangelogWriter` you will need to import the base `ChangelogWriter`\nclass.\n\nThis will ask for 2 methods to be available on the class. Below is a quick\ndescription of purpose behind each of those methods.\n\n- `write(filePath: string, newContent: string): Promise\u003cboolean\u003e` \u0026ndash; Takes\n  the filePath (determined at runtime), the new content based on the value\n  returned from chosen `generateChangelogEntry`\n- `generateChangelogEntry(newVersion: string, previousVersion: string,commits: Commit[]):`\n  \u0026ndash; Generates the actual entry that will be written in the CHANGELOG file\n  for the given `newVersion` (calculated by the `GitConvention`),\n  `previousVersion` (gathered by the `VersionStrategy`, and the commits,\n  gathered by any relevant CLI tool (and the `Git` class))\n\n#### Usage\n\n```ts\n// CustomChangelogWriter.ts\nimport {\n  type Args,\n  ChangelogWriter,\n  Commit,\n  Git,\n  GitProvider,\n  inject,\n  injectable,\n} from 'https://deno.land/x/version_bump/mod.ts';\n\n@injectable()\nexport default class CustomChangelogWriter extends ChangelogWriter {\n  // Needed to make the compiler happy.\n  public provider: GitProvider = new GitProvider();\n  /**\n   * Please note that the constructor does not have a given form -- it can use any of the [injectables](#injectables) in the code base. The signature used for the default is given below for reference\n   */\n  constructor(\n    @inject('gitProvider') public readonly gitProvider: GitProvider,\n    @inject('args') public readonly args: Args,\n    @inject('logger') public readonly log: LoggerInstance,\n    @inject(Git) public readonly git: Git,\n  ) {\n    super();\n  }\n\n  async write(\n    filePath: string,\n    newContent: string,\n  ): Promise\u003cboolean\u003e {\n    /// implementation here\n  }\n\n  generateChangelogEntry(\n    newVersion: string,\n    previousVersion: string,\n    commits: Commit[],\n  ): Promise\u003cstring\u003e {\n    /// Implementation here.\n  }\n}\n```\n\nThen, when you call the file you would use it as follows\n\n```sh\nversion-bump --changelogWriter ./CustomChangelogWriter.ts\n```\n\n### Making a Version Strategy\n\nThe `VersionStrategy` class is used to gather the current version of the\nproject. In general is a good idea to have a fallback to checking for git tags,\nplease see the implementation of the `DenoTsStrategy` to see how this could be\nimplemented.\n\nThe `VersionStrategy` requires the following two methods:\n\n- `bump(newVersion: string): Promise\u003cboolean\u003e` \u0026ndash; Takes in the version\n  calculated from our `GitConvention` and responsible for writing it into the\n  primary \u003cabbr title=\"Source of Truth\"\u003eSoT\u003c/abbr\u003e. Should return `true` for\n  successful writes, and `false` upon any failure (or simply `throw`-ing the\n  error is acceptable as well).\n- `getCurrentVersion(): Promise\u003cstring\u003e` \u0026ndash; Responsible for determining the\n  current version of the project. Should fallback to checking for Git tags if\n  version is not determinable otherwise.\n\n#### Usage\n\n```ts\n// CustomVersionStrategy.ts\nimport {\n  injectable,\n  VersionStrategy,\n} from 'https://deno.land/x/version_bump/mod.ts';\n\n@injectable()\nexport default class CustomVersionStrategy extends VersionStrategy {\n  bump(newVersion: string): Promise\u003cboolean\u003e {\n    // Code here\n  }\n  getCurrentVersion(): Promise\u003cstring\u003e {\n    //Code here\n  }\n}\n```\n\nTo use your custom VersionStrategy you would supply the argument as such:\n\n```sh\n# Project-specific\nversion-bump --versionStrategy CustomVersionStrategy.ts\n# Hosted somewhere\nversion-bump --versionStrategy https://company-website.com/CustomVersionStrategy.ts\n```\n\n### Making a Git Provider\n\nThe `GitProvider` class is injected at runtime, determined by the origin URL. We\ninclude 3 providers:\n\n- GitHub\n- GitLab\n- BitBucket\n\nHowever, if you are using a custom Git hosting provider that isn't supported you\ncan create your own. The GitProviders require the following methods:\n\n- `gitDiffUrl(from: string, to?: string): string` \u0026ndash; The URL for the\n  web-viewable difference editor.\n- `commitUrl(commit: string): string` \u0026ndash; The URL for the web-viewable\n  changes for a single commit.\n\n#### Usage\n\n```ts\nimport { GitProvider } from 'https://deno.land/x/version_bump/mod.ts';\n// NOTE: This class should NOT be injectable and it _should_ have a constructor that matches the one below.\nexport default class CustomProvider extends GitProvider {\n  constructor(url: URL) {}\n  gitDiffUrl(from: string, to = 'HEAD'): string {\n    // Code\n  }\n  commitUrl(commit: string): string {\n    // code\n  }\n}\n```\n\nTo use, you would provide the argument like so\n\n```sh\n# Local to the current file\nversion-bump --gitProvider customProvider.ts\n# Local, located in a different directory\nversion-bump --gitProvider ../../customProvider.ts\n# Shared somewhere else\nversion-bump --gitProvider https://esm.sh/some-preset/mod.ts\n```\n\n### Making a Git Convention\n\nThe `GitConvention` is the real powerhorse here. To make one you would need need\nthe following code\n\nThe GitConvention expects two methods:\n\n- `calculateBump(args: CalculateBumpArgs): Promise\u003cstring\u003e` \u0026ndash; Calculates\n  the bump based on the current Args, the current version resolved through the\n  `VersionStrategy`, and the gathered `Commits`.\n- `generateCommit(args: GenerateCommitArgs): Promise\u003cstring\u003e` \u0026ndash; Generates\n  the new commit based off the custom convention's standards. For example, the\n  Angular convention takes the default bump to be a `patch` level bump,\n  increasing the last number of a semantic version such as `x.y.z` by one. If\n  there are any features, this counts as a minor release, and would bump the `y`\n  value by one. Any release that broke the forward API would count as a major\n  release and would break the `x` value of the example.\n\n#### Usage\n\n```ts\n// CustomConvention.ts\nimport {\n  CalculateBumpArgs,\n  GenerateCommitArgs,\n  GitConvention,\n  injectable,\n} from 'https://deno.land/x/version_bump/mod.ts';\n\n@injectable()\nexport default class CustomConvention extends GitConvention {\n  calculateBump(args: CalculateBumpArgs): Promise\u003cstring\u003e {\n    // Code\n  }\n  generateCommit(args: GenerateCommitArgs): Promise\u003cstring\u003e {\n    // Code\n  }\n}\n```\n\nYou would use this in the command like as follows:\n\n```sh\nversion-bump --preset ./CustomConvention.ts\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhechtf%2Fversion-bump","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhechtf%2Fversion-bump","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhechtf%2Fversion-bump/lists"}