Git Semantic Versioning Plugins

Introduction

git-semver can run its own plugins. These are self contained executable files that live under either:

Location	Contains
`./.git-semver/plugins`	Project plugins (added and committed) which run on just the current git project
`${HOME}/.git-semver/plugins/`	User plugins which run on all git projects

Plugin can stop a tag being generated (for example if a version file does not exist).

See Contributing for detail on creating a plugin or take a look at the example plugin or any of the real plugins.

Installation

Plugins can be installed by copying them into .git-semver/plugins/ in either the project or under the user's home directory.

Plugins

Keep A Changelog - `keepachangelog.sh`

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

git-semver uses changelog convention from Keep a CHANGELOG. A changelog lists notable changes for each release of a project.

For a new version to be generated, a changelog must have already been commited which includes:

Details of the version (including version number and date)
A list of changes under one or more of the headings:
- Added for new features.
- Changed for changes in existing functionality.
- Deprecated for once-stable features removed in upcoming releases.
- Removed for deprecated features removed in this release.
- Fixed for any bug fixes.
- Security to invite users to upgrade in case of vulnerabilities.
An updated unreleased link at the bottom of the file
A version link at the bottom of the file

## [{{new version}}] - {{YYYY-MM-DD}}

### Added
- Details...

...

[unreleased]: https://github.com/oban/oban-site/compare/{{new version}}...HEAD
[{{new version}}]: https://github.com/oban/oban-site/compare/{{current version}}...{{version}}

See Keep a CHANGELOG for full details.

NPM `package.json` - `npmpackagejson.sh`

The package.json file is used by NPM, typically for Node.js applications, however can also be used in other projects where development tools (such as runners or builders like Gulp or Grunt) or languages like CoffeeScript or SASS are required.

package.json includes a version property, which npmpackagejson.sh will check:

{
   ...
   "version": "3.2.1",
   ...
}

Major and minor tags - [`90-major_and_minor_tag.sh`]

This plugins creates 2 extra tags each time you git-semver major or git-semver minor, one with the minor version and other with the major one.

In other words, if you create a 3.0.0 version, this plugin will also create a 3.0 and 3 tag. Also, if you create a 3.1.0 tag, it will delete the previously created 3 tag, and create it again pointing to the 3.1.0 commit, together with a brand new 3.1 tag.

This is useful, for example, to maintain multiple versions of an API: If you have a legacy version 1.5.3 API you need to maintain, and a new version 2, you can use this plugin to maintain a "rolling" 1.5 tag, and always deploy the latest bugfix for your legacy API, and maybe build against a 2 tag for the new one, to get the latest features.

Python `setup.py` - [`setuppy_update.sh`]

This plugin makes sure you never forget to update your package version.

When active, it will search for a setup.py file in the root of the project, and change the version argument passed to the setup class to the version being tagged. Then, it will commit it with a "Updated setup.py version" message.

Contributing

A plugin can be any executable file stored in .git-semver/plugins/.

Description

If the first parameter is --about, then the plugin should print a one-line description of itself, and exit 0.

Parameters

The plugins must take the positional parameters:

Parameter	Value
`version_new`	Version git-semver is attempting to add
`version_current`	Current version the project is at (or blank if no version)
`git_hash`	The current full SHA-1 hash
`git_branch`	The current local branch
`git_root`	The full path of the git project

All or none of these may be used.

Exit codes

The plugin must exit with one of the codes:

Exit Code	Meaning
`0`	No error
`111`	Warning: continue processing plugins and apply version
`112`	Error: continue processing plugins (to allow other generated errors) but stop before applying version tag
`113`	Fatal error: stop immediately

Any other codes are ignored, and will cause git-semver to continue processing plugins and apply a version.

Output

Plugins can print anything to stdout or stderr. This will be formatted and displayed by git-semver.

Pull requests

Please contribute your plugin by opening a pull request.

See CONTRIBUTING.md for more details.

Notes

Plugin format was borrowed from Git hooks.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!