Giter Site home page Giter Site logo

purpleclay / nsv Goto Github PK

View Code? Open in Web Editor NEW
4.0 2.0 0.0 4.11 MB

Semantic versioning without any config

Home Page: https://docs.purpleclay.dev/nsv/

License: MIT License

Go 87.21% Shell 10.53% Dockerfile 1.62% Nix 0.64%
conventional-commits go semver semver-release git semantic-versioning no-config

nsv's Introduction

NSV

NSV (Next Semantic Version) is a convention-based semantic versioning tool that leans on the power of conventional commits to make versioning your software a breeze!

See it in action

nsv.mp4

Why another versioning tool

There are many semantic versioning tools already out there! But they typically require some configuration or custom scripting in your CI system to make them work. No one likes managing config; it is error-prone, and the slightest tweak ultimately triggers a cascade of change across your projects.

Step in NSV. Designed to make intelligent semantic versioning decisions about your project without needing a config file. Entirely convention-based, you can adapt your workflow from within your commit message.

The power is at your fingertips.

Features

  • First-class support for semantic versioning. Conventional commits help give it a nudge in the right direction.
  • If you batch your commits per release or prefer a continuous delivery approach, it has you covered.
  • Context-aware, it automatically switches to a monorepo workflow.
  • Extend the power of your commits through commands to dynamically change your semantic release workflow.
  • Explore how to use it within the purpose-built playground.
  • Get up and running in seconds within GitHub and GitLab with the available action or template.

Documentation

Check out the latest documentation

Badges

Build status License MIT Go Version DeepSource

nsv's People

Contributors

dependabot[bot] avatar purpleclay avatar

Stargazers

avatar avatar avatar avatar

Watchers

avatar avatar

nsv's Issues

[Feature]: build an initial version of the playground for exploring how to use nsv

Describe your feature

Build a playground TUI that can be launched from the nsv CLI. The initial version of the playground should allow exploration of nsv features and how they impact the construction of a tag. For this initial version, load a pseudo repository into memory that the user can edit to trigger different behaviours within nsv.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: include gpg-import within docker container to support gpg signing

Describe your feature

Bundle the gpg-import tool within the container and call it if the GPG_PRIVATE_KEY environment variable is set. It would be best to invoke this through an entrypoint.sh script. Ensure nsv is aligned with the environment variables that are set.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: support a pretty mode for outputting the table in different formats

Describe your feature

Add a new --pretty flag and NSV_PRETTY environment variable to be used in conjunction with the --show flag to change the formatting of the table.

Support two initial modes: full and compact. full is the default mode for a single tag

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Docs]: write documentation for release 0.4.0

Describe your edit

Update the documentation as part of release 0.4.0:

  • impersonation support
  • improved UX when showing how semver is calculated

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Docs]: write basic documentation for version 0.1.0

Describe your edit

Write basic documentation for version 0.1.0 of nsv. Ensure to reinforce that it is a semantic version utility currently tied to conventional commits. Its aim is to be zero-config and driven purely by the convention of commit messages.

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: expose existing functionality behind a next command

Describe your feature

After introducing a new nsv format command it seems right to move the existing logic behind a new nsv next command. This will ensure a consistent look and feel within the CLI as need commands are added in future

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: auto-detect semantic prefix based on the project programming language for initial version

Describe your feature

When generating the initial semantic version, nsv defines placeholders that can be passed to the NSV_FORMAT environment variable (or --format flag). This has the potential to be error-prone and requires this format to be unnecessarily defined in most situations. Update nsv to scan its context directory for known programming languages and construct the initial semantic version based on the convention of that language. This behaviour can be overwritten by setting either the `` environment variable or --format flag.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Docs]: write documentation for version 0.2.0

Describe your edit

Document the following updates ready for version 0.2.0:

  • new command added to tag a repository
  • gpg signing of tags supported by using a default annotation

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: allow multiple paths to be processed simultaneously

Describe your feature

Expand the existing next and tag commands to support multiple paths as arguments:

nsv next src/ui src/store

If multiple paths are provided, nsv will spawn internal Go routines to calculate each semantic version in parallel. The output will be a comma-separated list of tags matching the provided path order.

ui/0.2.0,store/0.3.2

When --show is provided, a new multi-tag tui will display the output in a tabular format:

| ui/0.2.0      | HEAD                        |
|               | feat: this is a commit      |
|               |                             |
|               | fix: this is another commit |
|               | ui/0.1.0                    | 
| store/0.3.2   | HEAD                        |
|               | fix: this is a bug fix      |
|               | store/0.3.1                 |

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: allow all colour output to be disabled

Describe your feature

Provide a flag --no-color and environment variable NO_COLOR for disabling colour output within nsv.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[CI]: package up and publish nsv as a container

Describe your enhancement

To support the use of nsv within other CI environments, it should be published as a docker image. Update the existing GoReleaser configuration to support this

Code of Conduct

  • I agree to follow this project's Code of Conduct

[CI]: improve usage of golangci-lint by revising existing parser list

Describe your enhancement

The existing use of golangci-lint was based on generating a report for SonarCloud. Having switched away from this product, it seems the job needs reworking as it doesn't fail the workflow. It seems about right to check the config as well. Maybe this can be dynamically set during the job instead of having to keep a local copy in each repository.

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: add support for triggering a prerelease through an nsv command

Describe your feature

nsv strictly adheres to the SemVer v2 spec, making working with prereleases cumbersome, especially when triggered through Conventional Commits. Add support for a new command that allows a prerelease to be triggered through a commit:

nsv:pre

The initial format of a prerelease label will be -beta.{{ .counter }} e.g. -beta.1, followed by -beta.2

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: verify custom template before calculating the next version

Describe your feature

Add logic that verifies the provided go template for syntactic issues. The verification logic will need to be aware of all supported template parameters. Report a custom failure back to the client when raising this error.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: support GPG signing of tags

Describe your feature

Ensure nsv will sign any tags if the repository has been configured to use GPG keys. Initially, this will be supported by always creating an annotated tag, a prerequisite for signing tags.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: allow prerelease label to be specified with pre command

Describe your feature

nsv currently only supports generating prerelease tags with the beta label. Extend the new pre command to support an optional label: alpha, beta and rc.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Bug]: incorrect log path resolution when executing nsv from within a subdirectory

What happened?

When executing nsv from within a sub-directory, no commits are being retrieved from the log. nsv incorrectly detects its location and passes an incorrect log path during log retrieval.

Steps to reproduce it

  1. Create a nested sub-directory within a git repository e.g. src/ui
  2. Add a test file and commit
  3. Run nsv from within the src/ui directory. No log is retrieved

Which version?

v0.3.0

Which operating system(s) are you using?

All

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: use a custom usage template with cobra for improved formatting

Describe your feature

Create a custom usage template compatible with cobra for improved formatting of usage text. Presently when a long description is provided for a flag, no word wrapping is used:

Flags:
  -f, --format string   provide a go template for changing the default version format
  -h, --help            help for next
  -p, --pretty string   pretty-print the output of the next semantic version in a given format. The format can be one of either full or compact. full is the default. Must be used in conjunction with --show (default "full")
  -s, --show            show how the next semantic version was generated

Write a Go template that is capable of producing output similar to the rust library clap:

Options:
  -k, --key <BASE64_ARMORED_KEY>
          A base64 encoded GPG private key in armored format

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: support go templated string for custom tag message

Describe your feature

Include support for a go-templated string when defining a custom annotated tag message. Data that should be made available to the template are:

  • Tag
  • Previous Tag

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: build a cli that is capable of calculating the next semantic version without any config

Describe your feature

Build a prototype version of the CLI that can calculate the next semantic version based on the repository's history. It should be aware of the sub-directory it executes within to automatically handle a mono repo by prefixing any semantic version with a component name (i.e. the name of the sub-directory).

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: ensure summary clearly describes how increment was determined

Describe your feature

nsv includes an option to display how the next semantic version was calculated (--show or NSV_SHOW=1). It currently relies on colour for a user to disseminate the information. Rework the existing tui to display this information better.

An example of the output should be:

$ nsv next --show
0.11.5

HEAD (src/backend)
----------------------------------------------------------------------
✔️ 80cf453
  <fix:> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 
  eiusmod tempor incididunt ut labore et dolore magna aliqua

4dfdb18
docs: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 
eiusmod tempor incididunt ut labore et dolore magna aliqua
----------------------------------------------------------------------
0.11.4

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Bug]: summary truncates the log directory in its output

What happened?

When displaying the summary nsv appears to truncate the path of the log directory. In this instance it should display (dir: src/search) but it currently displays (dir: search):

$ nsv next --show src/search
search/0.2.0

┌────────────────────┬─────────────────────────────────────────────────────────────────────────────────┐
│ search/0.2.0       │(dir: search)                                                                    │
│ ↑↑                 │                                                                                 │
│ search/0.1.1       │✓ fc3f0d4                                                                        │
│                    │  feat!: a cool new feature                                                      │
│                    │                                                                                 │
│                    │> 9046cac                                                                        │
│                    │  feat: a cool new feature                                                       │
├────────────────────┼─────────────────────────────────────────────────────────────────────────────────┤

Steps to reproduce it

  1. nsv next --show src/ui

Which version?

v0.4.0

Which operating system(s) are you using?

All

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: support the concept of a semver major version zero development workflow

Describe your feature

To be as compliant as possible with semantic versioning, nsv needs to support the concept of major version zero development 0.y.z, where lots of change will occur before the first stable version of 1.0.0 is reached. In this situation, a breaking change shouldn't increment the major version number and should be capped to minor updates.

Extracts from the spec:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. 
The public API SHOULD NOT be considered stable.

and

Major version zero is all about rapid development. If you’re changing the API every day you should either 
still be in version 0.y.z or on a separate development branch working on the next major version.

A convention is needed to escape this mode and signify a breaking change. To keep to the zero-config mantra, a commit footer convention should be introduced to trigger expected behaviour.

feat!: this is a breaking change, and the API is now deemed stable

nsv: force:breaking

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: ensure the tag command outputs the tagged version

Describe your feature

Update the existing tag command to output the tag to stdout. This allows the GitLab Template and GitHub Action to capture the tag as an output for use within subsequent jobs.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: support the inclusion of multiple nsv commands

Describe your feature

nsv currently supports two commands, force and pre, but they can not be used together. Improve the parsing of the nsv command line to detect multiple commands. Each command should be separated with a , with optional whitespace on either side for flexibility.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: add simple logging to provide context to the calling user

Describe your feature

nsv does not currently have any log output. The only output shown is if the NSV_SHOW or --show flag is provided. To highlight decisions made, for example, add some simple logging throughout the nsv workflow.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Bug]: fails to run within GitLab due to no tty being present

What happened?

If no tty is detected, nsv will fail to create an annotated tag. The following error message is reported:

$ nsv tag

error: gpg failed to sign the data:
[GNUPG:] KEY_CONSIDERED A0D29792989F951A815D2D831FD164C414C63F44 2
[GNUPG:] BEGIN_SIGNING H10
[GNUPG:] PINENTRY_LAUNCHED [49](https://gitlab.com/purpleclay/nsv-test/-/jobs/4555762909#L49) curses 1.2.1 - - - - 0/0 0
gpg: signing failed: Not a tty
[GNUPG:] FAILURE sign 839189[50](https://gitlab.com/purpleclay/nsv-test/-/jobs/4555762909#L50)
gpg: signing failed: Not a tty
error: unable to sign the tag

Steps to reproduce it

  1. Create a GitLab project with a pipeline that imports the following job:
include:
  - https://gitlab.com/purpleclay/nsv/-/raw/add-nsv-job-template/nsv.gitlab-ci.yml

### Which version?

0.2.0

### Which operating system(s) are you using?

All

### Code of Conduct

- [X] I agree to follow this project's Code of Conduct

[Feature]: protect against invalid creation of prerelease tags

Describe your feature

As nsv now supports the pre command with an optional label. It needs to query the last prerelease tag to avoid a tag conflict if the user accidentally switches between prerelease stages, e.g., beta ~> alpha~>beta. If this did happen, nsvshould produce the following tag as0.1.0-beta.2and not0.1.0-beta.1, as it already exists. This would put nav` into an unrecoverable state and require manual intervention from the user.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: add an option to tag with an annotated tag

Describe your feature

When tagging a repository with the next semantic version, add an option using a flag and environment variable to create an annotated tag.

  • --annotated
  • NSV_TAG_ANNOTATED=1

Mirror the options provided by git tag and include a --message flag that supports a custom annotation message and implies an annotated tag.

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: allow nsv to impersonate a user

Describe your feature

For nsv to impersonate a user, it must scan all commits between two refs and identify which user a particular commit belongs to. That user will be used when generating the tag. Impersonation is unnecessary if the git config for the repository is configured or the reserved environment variables GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL are set.

Impersonation is not a permanent action, so avoid setting any config. Some git actions support temporary config settings through flags. Temporarily setting environment variables is also an option.

Any additional information?

The annotation assigned to the tag should be expanded to include details of the commit that triggered the next semantic version.

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Docs]: include initial prerelease support within 0.7.0 documentation

Describe your edit

Update the existing documentation to include details on how to use the experimental prerelease support within nsv.

  • Remove the experimental label from the semantic commands page; this is now stable
  • Add a section on the use of prerelease labels.
  • Remove the experimental label from the main page about commands.

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Docs]: write documentation for release 0.5.0

Describe your edit

Update existing documentation to include the following new features:

  • Pretty mode for improved formatting of output
  • Go templating support for tag message
  • Relative paths can be provided to tag multiple versions at the same time

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Docs]: add docker installation options

Describe your edit

As nsv is now published as a docker container across multiple platforms, provide instructions on how to run nsv from a container.

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: add support for configurable conventional commit prefixes

Describe your feature

Add support for configuring the conventional commit prefixes used by nsv to determine how a semantic version should be incremented. Each option should support a comma-separated list of prefixes.

  • --major-prefixes or NSV_MAJOR_PREFIXES
  • --minor-prefixes or NSV_MINOR_PREFIXES
  • --patch-prefixes or NSV_PATCH_PREFIXES

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Feature]: support customisation of the internal version template

Describe your feature

Internally nsv uses a Go template to generate the next version number from a parsed tag. Allow this template to be overridden through a flag or environment variable. Provide an additional flag that can be used to verify a template

Any additional information?

No response

Code of Conduct

  • I agree to follow this project's Code of Conduct

[Bug]: use the base directory when calculating the tag prefix when run outside of the root git directory

What happened?

The tag prefix is currently based on the relative location of nsv to the root directory of the git repository. This needs to be further refined, not to include nested directories. For example, running nsv within src/ui should generate a tag prefix of ui.

Steps to reproduce it

  1. Run nsvwithin a sub-directory of the repository using nsv next --show

Which version?

v0.3.0

Which operating system(s) are you using?

All

Code of Conduct

  • I agree to follow this project's Code of Conduct

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.