-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.md.template
131 lines (91 loc) · 5.01 KB
/
README.md.template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
# github-next-semantic-version
[](https://goreportcard.com/report/github.com/fabien-marty/github-next-semantic-version)
## What is it?
`github-next-semantic-version` is a little CLI binary (written in golang) to
**guess the next [semantic version](https://semver.org/)** from:
- existing **git tags** *(read from a locally cloned git repository)*
- and recently merged **pull-requests labels** *(read from the GitHub API)*
Unlinke plenty of "similar" tools, we don't use any "commit message parsing" here but only
**configurable PR labels**.
Example *(with a repo cloned in the current directory)*:
```console
$ github-next-semantic-version .
v1.10.0 => v1.10.1
$ # v1.10.0 is the latest version
$ # v1.10.1 is the next version
```
> [!TIP]
> **How do we determine the next version? How do we determine if the next version is a patch/minor/major version?**
>
> - we list PRs merged since the latest tag
> - we examine corresponding PR labels:
> - if we find at least one `breaking` or `Type: Major` label => this is a major release *(so we increment the major version number)*
> - if we find at least one `feature` or `Type: Feature` label => this is a minor release *(so we increment the minor version number)*
> - else this is a patch release
>
> *(of course, you can define your own labels to configure the logic)*
> [!NOTE]
> We also provide:
>
> - a dedicated GitHub Action in [this dedicated repository](https://github.com/fabien-marty/github-next-semantic-version-action) *if you want to use this tool inside a GHA workflow*
> - another CLI binary: `github-create-next-semantic-release` *(in this current repository)* to use the previous rules to automatically create a GitHub release with the guessed version and the corresponding release notes *(made from merged PRs and a configurable template)*
> - another GitHub Action in [this other repository](https://github.com/fabien-marty/github-create-next-semantic-release-action) *if you want to use this alternate tool: `github-create-next-semantic-release` inside a GHA workflow*
> - a full changelog generator CLI: `github-generate-changelog` (configurable by a [golang text/template](https://pkg.go.dev/text/template))
## Features
- support full semver specification (basic `1.2.3` but also `1.0.0-beta.2`, `0.1.9-post.24_a5256f1`...)
- can filter tags with regex (see `--tag-regex` option)
- support prefixed tags (example: `v1.2.3` but also `foo/bar/v1.2.3`...) when parsing the semantic version
- configure your own PR labels for major and minor increments
- ... (see "CLI reference" in this document)
- addon binary to automatically create GitHub releases with the guessed version and corresponding release notes
- addon binary to generate full changelog
## Non-features
- "commit message parsing": there are plenty of tools to do that, here, we want to rely only on merged PR labels
- "other providers support": we support only "GitHub" *(feel free to fork if you want to add other providers support)*
## Installation / Quickstart
We provide compiled binaries for various architecture in the [release page](https://github.com/fabien-marty/github-next-semantic-version/releases).
- download the corresponding file
- set the "executable bit"
- clone a public repository locally (with all tags)
- execute `./github-next-semantic-version .`
*(same for `github-create-next-semantic-release` binary)*
> [!NOTE]
> Of course it also works with private repositories but you will need a GitHub token
> set to `GITHUB_TOKEN` env var (for example).
## CLI reference
<details open>
<summary>CLI reference of github-next-semantic-version</summary>
```console
$ github-next-semantic-version --help
{{ "./cmd/github-next-semantic-version/github-next-semantic-version --help"|shell() }}
```
</details>
<details>
<summary>CLI reference of github-create-next-semantic-release</summary>
```console
$ github-create-next-semantic-release --help
{{ "./cmd/github-create-next-semantic-release/github-create-next-semantic-release --help"|shell() }}
```
</details>
<details>
<summary>CLI reference of github-generate-changelog</summary>
```console
$ github-generate-changelog --help
{{ "./cmd/github-generate-changelog/github-generate-changelog --help"|shell() }}
```
</details>
## DEV
This tool is fully developped in Golang 1.21+ with following libraries:
- [github.com/Masterminds/semver V3](https://github.com/Masterminds/semver/): for semver parsing
- [github.com/google/go-github V62](https://github.com/google/go-github/): for GitHub API
- [github.com/urfave/cli V2](https://github.com/urfave/cli/): for CLI
We follow [golang-standards/project-layout](https://github.com/golang-standards/project-layout) directories structure
and we use "hexagonal architecture" with:
- domain/use-cases code in the `app` subdir
- IO adapters in the `infra/adapters` subdir
- CLI controller in the `infra/controllers` subdir
Dev commands are implemented inside a `Makefile` with following targets:
```console
$ make help
{{ "make help |sed 's/\x1b\[[0-9;]*m//g'"|shell() }}
```