docs: add tutorial to generate release with its changelog

Reviewed-on: #1

.chglog/CHANGELOG.tpl.md

@@ -0,0 +1,42 @@
+{{ if .Versions -}}
+<a name="unreleased"></a>
+## [Unreleased]
+
+{{ if .Unreleased.CommitGroups -}}
+{{ range .Unreleased.CommitGroups -}}
+### {{ .Title }}
+{{ range .Commits -}}
+- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
+{{ end }}
+{{ end -}}
+{{ end -}}
+{{ end -}}
+
+{{ range .Versions }}
+<a name="{{ .Tag.Name }}"></a>
+## {{ if .Tag.Previous }}[{{ .Tag.Name }}]{{ else }}{{ .Tag.Name }}{{ end }} - {{ datetime "2006-01-02" .Tag.Date }}
+{{ range .CommitGroups -}}
+### {{ .Title }}
+{{ range .Commits -}}
+- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
+{{ end }}
+{{ end -}}
+
+{{- if .NoteGroups -}}
+{{ range .NoteGroups -}}
+### {{ .Title }}
+{{ range .Notes }}
+{{ .Body }}
+{{ end }}
+{{ end -}}
+{{ end -}}
+{{ end -}}
+
+{{- if .Versions }}
+[Unreleased]: {{ .Info.RepositoryURL }}/compare/{{ $latest := index .Versions 0 }}{{ $latest.Tag.Name }}...HEAD
+{{ range .Versions -}}
+{{ if .Tag.Previous -}}
+[{{ .Tag.Name }}]: {{ $.Info.RepositoryURL }}/compare/{{ .Tag.Previous.Name }}...{{ .Tag.Name }}
+{{ end -}}
+{{ end -}}
+{{ end -}}

.chglog/config.yml

@@ -0,0 +1,33 @@
+style: github
+template: CHANGELOG.tpl.md
+info:
+  title: CHANGELOG
+  repository_url: https://forge.cadoles.com/Cadoles/mktools
+options:
+  commits:
+    filters:
+      Type:
+        - feat
+        - fix
+        - perf
+        - refactor
+        - docs
+  commit_groups:
+    title_maps:
+      feat: Features
+      fix: Bug Fixes
+      perf: Performance Improvements
+      refactor: Code Refactoring
+      docs: Documentation
+  header:
+    pattern: "^(\\w*)(?:\\(([\\w\\$\\.\\-\\*\\s]*)\\))?\\:\\s(.*)$"
+    pattern_maps:
+      - Type
+      - Scope
+      - Subject
+  notes:
+    keywords:
+      - BREAKING CHANGE
+  issues:
+    prefix:
+      - '#'

.gitignore

@@ -0,0 +1 @@
+tools/

CHANGELOG.md

@@ -0,0 +1,32 @@
+<a name="unreleased"></a>
+## [Unreleased]
+
+
+<a name="2023.8.23-stable.1608.9730ec9"></a>
+## [2023.8.23-stable.1608.9730ec9] - 2023-08-23
+
+<a name="2023.8.23-stable.1545.643e170"></a>
+## [2023.8.23-stable.1545.643e170] - 2023-08-23
+
+<a name="2023.8.23-stable.1545.2f77f3e"></a>
+## [2023.8.23-stable.1545.2f77f3e] - 2023-08-23
+### Bug Fixes
+- **changelog:** add missing task dependency
+
+### Features
+- add changelog
+- add mkt-changelog task
+- **gitea-release:** automatically add tools directory to git ignored files
+- **version:** use master and staging branches as aliases for testing and stable
+
+
+<a name="2023.8.23-stable.1207.cd2f1ba"></a>
+## 2023.8.23-stable.1207.cd2f1ba - 2023-08-21
+### Features
+- initial commit
+
+
+[Unreleased]: https://forge.cadoles.com/Cadoles/mktools/compare/2023.8.23-stable.1608.9730ec9...HEAD
+[2023.8.23-stable.1608.9730ec9]: https://forge.cadoles.com/Cadoles/mktools/compare/2023.8.23-stable.1545.643e170...2023.8.23-stable.1608.9730ec9
+[2023.8.23-stable.1545.643e170]: https://forge.cadoles.com/Cadoles/mktools/compare/2023.8.23-stable.1545.2f77f3e...2023.8.23-stable.1545.643e170
+[2023.8.23-stable.1545.2f77f3e]: https://forge.cadoles.com/Cadoles/mktools/compare/2023.8.23-stable.1207.cd2f1ba...2023.8.23-stable.1545.2f77f3e

Jenkinsfile

@@ -0,0 +1,6 @@
+@Library("cadoles") _
+
+standardMakePipeline([
+    'buildTask': null,
+    'releaseTask': null
+])

Makefile

@@ -0,0 +1,38 @@
+.PHONY: all
+all: test build
+
+.PHONY: test
+test: tools/checkmake/bin/checkmake
+	tools/checkmake/bin/checkmake Makefile
+
+MKT_GITEA_RELEASE_ORG ?= Cadoles
+MKT_GITEA_RELEASE_PROJECT ?= mktools
+
+.PHONY: release
+release:
+	git tag $(MKT_PROJECT_VERSION) && git push --tags
+	$(MAKE) update-changelog
+	$(MAKE) MKT_GITEA_RELEASE_ATTACHMENTS="$(MKT_GITEA_RELEASE_ATTACHMENTS) CHANGELOG.md" \
+		MKT_GITEA_RELEASE_COMMIT_TARGET="$(MKT_PROJECT_VERSION)" \
+		mkt-gitea-release
+
+.PHONY: clean
+clean:
+	rm -rf tools
+
+.PHONY: update-changelog
+update-changelog:
+	$(MAKE) changelog
+	git add CHANGELOG.md
+	git commit -m "chore: update changelog"
+	git push
+
+.PHONY: changelog
+changelog:
+	git fetch --prune-tags
+	$(MAKE) \
+		MKT_GIT_CHGLOG_PROJECT_ORG=$(MKT_GITEA_RELEASE_ORG) \
+		MKT_GIT_CHGLOG_PROJECT_NAME=$(MKT_GITEA_RELEASE_PROJECT) \
+		mkt-changelog
+
+include tasks/*.mk

README.md

@@ -36,4 +36,9 @@ Tâches [Make](https://fr.wikipedia.org/wiki/Make) génériques à utiliser de p
 |Tâches|Description|Documentation|
 |------|-----------|-------------|
 |`make mkt-webdav-upload`|Téléverser un fichier dans un répertoire WebDAV (Nextcloud)|[Voir ./doc/tasks/webdav.md](./doc/tasks/webdav.md)|
-|`make mkt-gitea-release`|Créer une release sur un projet Gitea et téléverser des fichiers attachés|[Voir ./doc/tasks/gitea.md](./doc/tasks/gitea.md)|
+|`make mkt-gitea-release`|Créer une release sur un projet Gitea et téléverser des fichiers attachés|[Voir ./doc/tasks/gitea.md](./doc/tasks/gitea.md)|
+|`make mkt-changelog`|Générer un fichier de `CHANGELOG.md` pour votre projet|[Voir ./doc/tasks/changelog.md](./doc/tasks/changelog.md)|
+
+## Tutoriels
+
+- [Créer une "release" avec son fichier `CHANGELOG.md`](./doc/tutorials/generate-release-with-changelog.md)

doc/tasks/changelog.md

@@ -0,0 +1,26 @@
+# Tâches Changelog
+
+## `make mkt-changelog`
+
+La tâche `mkt-changelog` permet de générer un fichier `CHANGELOG.md` avec l'outil [`git-chglog`](https://github.com/git-chglog/git-chglog) et de l'historique Git de votre projet.
+
+L'usage de cette tâche a pour prérequis que vos messages de commit respectent la spécification ["Conventional Commit"](https://www.conventionalcommits.org/fr/v1.0.0/).
+
+Par défaut voici [les types de commit](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type) référencés par le fichier généré:
+
+- `feat`
+- `fix`
+- `perf`
+- `refactor`
+- `docs`
+
+### Usage
+
+Exemple d'utilisation de la tâche pour la génération du changelog du projet `https://forge.cadoles.com/MyOrg/MyProject` sur la forge:
+
+```makefile
+my-changelog:
+	$(MAKE) MKT_GIT_CHGLOG_PROJECT_ORG=MyOrg MKT_GIT_CHGLOG_PROJECT_NAME=MyProject mkt-changelog
+```
+
+> **Note** Assurez vous d'avoir créé un premier tag sur la branche en cours avant d'exécuter la tâche.

doc/tutorials/generate-release-with-changelog.md

@@ -0,0 +1,34 @@
+# Générer une release pour son projet
+
+Afin de générer une release pour votre projet (exemple: https://forge.cadoles.com/Cadoles/mktools/releases/tag/2023.8.23-stable.1545.643e170) ainsi que le fichier `CHANGELOG.md` associé à votre historique Git, vous pouvez intégrer à votre `Makefile` les tâches suivantes:
+
+```makefile
+MKT_GITEA_RELEASE_ORG ?= MyOrg              # Propriétaire (organisation ou utilsateur) du projet Gitea
+MKT_GITEA_RELEASE_PROJECT ?= MyProject      # Nom du projet Gitea
+
+.PHONY: release
+release:
+	git tag $(MKT_PROJECT_VERSION) && git push --tags
+	$(MAKE) update-changelog
+	$(MAKE) MKT_GITEA_RELEASE_ATTACHMENTS="$(MKT_GITEA_RELEASE_ATTACHMENTS) CHANGELOG.md" \
+		MKT_GITEA_RELEASE_COMMIT_TARGET="$(MKT_PROJECT_VERSION)" \
+		mkt-gitea-release
+
+.PHONY: update-changelog
+update-changelog:
+	$(MAKE) changelog
+	git add CHANGELOG.md
+	git commit -m "chore: update changelog"
+	git push
+
+.PHONY: changelog
+changelog:
+	git fetch --prune-tags
+	$(MAKE) MKT_GIT_CHGLOG_PROJECT_ORG=$(MKT_GITEA_RELEASE_ORG) MKT_GIT_CHGLOG_PROJECT_NAME=$(MKT_GITEA_RELEASE_PROJECT) mkt-changelog
+```
+
+Pour générer une release sur votre projet, il vous suffira ensuite de faire:
+
+```shell
+make release
+```

tasks/changelog.mk

@@ -0,0 +1,110 @@
+MKT_GIT_CHGLOG_VERSION ?= 0.15.4
+MKT_GIT_CHGLOG_DOWNLOAD_URL ?= https://github.com/git-chglog/git-chglog/releases/download/v$(MKT_GIT_CHGLOG_VERSION)/git-chglog_$(MKT_GIT_CHGLOG_VERSION)_linux_amd64.tar.gz
+MKT_GIT_CHGLOG_ARGS ?=
+MKT_GIT_CHGLOG_PROJECT_ORG ?= 
+export MKT_GIT_CHGLOG_PROJECT_ORG
+MKT_GIT_CHGLOG_PROJECT_NAME ?= 
+export MKT_GIT_CHGLOG_PROJECT_NAME
+
+define _MKT_GIT_CHGLOG_CONFIG_SCRIPT =
+mkdir -p .chglog
+cat > .chglog/config.yml << EOF
+style: github
+template: CHANGELOG.tpl.md
+info:
+  title: CHANGELOG
+  repository_url: https://forge.cadoles.com/${MKT_GIT_CHGLOG_PROJECT_ORG}/${MKT_GIT_CHGLOG_PROJECT_NAME}
+options:
+  commits:
+    filters:
+      Type:
+        - feat
+        - fix
+        - perf
+        - refactor
+        - docs
+  commit_groups:
+    title_maps:
+      feat: Features
+      fix: Bug Fixes
+      perf: Performance Improvements
+      refactor: Code Refactoring
+      docs: Documentation
+  header:
+    pattern: "^(\\\\w*)(?:\\\\(([\\\\w\\\\$\\\\.\\\\-\\\\*\\\\s]*)\\\\))?\\\\:\\\\s(.*)$"
+    pattern_maps:
+      - Type
+      - Scope
+      - Subject
+  notes:
+    keywords:
+      - BREAKING CHANGE
+  issues:
+    prefix:
+      - '#'
+EOF
+endef
+export MKT_GIT_CHGLOG_CONFIG_SCRIPT = $(value _MKT_GIT_CHGLOG_CONFIG_SCRIPT)
+
+define _MKT_GIT_CHGLOG_TEMPLATE_SCRIPT =
+mkdir -p .chglog
+cat > .chglog/CHANGELOG.tpl.md << EOF
+{{ if .Versions -}}
+<a name="unreleased"></a>
+## [Unreleased]
+
+{{ if .Unreleased.CommitGroups -}}
+{{ range .Unreleased.CommitGroups -}}
+### {{ .Title }}
+{{ range .Commits -}}
+- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
+{{ end }}
+{{ end -}}
+{{ end -}}
+{{ end -}}
+
+{{ range .Versions }}
+<a name="{{ .Tag.Name }}"></a>
+## {{ if .Tag.Previous }}[{{ .Tag.Name }}]{{ else }}{{ .Tag.Name }}{{ end }} - {{ datetime "2006-01-02" .Tag.Date }}
+{{ range .CommitGroups -}}
+### {{ .Title }}
+{{ range .Commits -}}
+- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
+{{ end }}
+{{ end -}}
+
+{{- if .NoteGroups -}}
+{{ range .NoteGroups -}}
+### {{ .Title }}
+{{ range .Notes }}
+{{ .Body }}
+{{ end }}
+{{ end -}}
+{{ end -}}
+{{ end -}}
+
+{{- if .Versions }}
+[Unreleased]: {{ .Info.RepositoryURL }}/compare/{{ \$latest := index .Versions 0 }}{{ \$latest.Tag.Name }}...HEAD
+{{ range .Versions -}}
+{{ if .Tag.Previous -}}
+[{{ .Tag.Name }}]: {{ $.Info.RepositoryURL }}/compare/{{ .Tag.Previous.Name }}...{{ .Tag.Name }}
+{{ end -}}
+{{ end -}}
+{{ end -}}
+EOF
+endef
+export MKT_GIT_CHGLOG_TEMPLATE_SCRIPT = $(value _MKT_GIT_CHGLOG_TEMPLATE_SCRIPT)
+
+mkt-changelog: tools/git-chglog/bin/git-chglog .chglog/config.yml .chglog/CHANGELOG.tpl.md
+	tools/git-chglog/bin/git-chglog --output CHANGELOG.md $(MKT_GIT_CHGLOG_ARGS)
+
+.chglog/config.yml:
+	@eval "$$MKT_GIT_CHGLOG_CONFIG_SCRIPT"
+
+.chglog/CHANGELOG.tpl.md:
+	@eval "$$MKT_GIT_CHGLOG_TEMPLATE_SCRIPT"
+
+tools/git-chglog/bin/git-chglog:
+	mkdir -p tools/git-chglog/bin
+	grep -qF -- "tools/" ".gitignore" 2>/dev/null || echo "tools/" >> ".gitignore"
+	( cd tools/git-chglog/bin && curl -sL "$(MKT_GIT_CHGLOG_DOWNLOAD_URL)" | tar -xz git-chglog )

tasks/checkmake.mk

@@ -0,0 +1,8 @@
+MKT_CHECKMAKE_VERSION ?= 0.2.2
+MKT_CHECKMAKE_URL ?= https://github.com/mrtazz/checkmake/releases/download/$(MKT_CHECKMAKE_VERSION)/checkmake-$(MKT_CHECKMAKE_VERSION).linux.amd64
+
+tools/checkmake/bin/checkmake:
+	mkdir -p tools/checkmake/bin
+	grep -qF -- "tools/" ".gitignore" 2>/dev/null || echo "tools/" >> ".gitignore"
+	curl -sL -o tools/checkmake/bin/checkmake  "$(MKT_CHECKMAKE_URL)"
+	chmod +x tools/checkmake/bin/checkmake

tasks/gitea.mk

@@ -1,7 +1,7 @@
 MKT_GITEA_RELEASE_PROJECT ?=
 MKT_GITEA_RELEASE_ORG ?=
 MKT_GITEA_RELEASE_BASE_URL ?= https://forge.cadoles.com
-MKT_GITEA_RELEASE_VERSION ?=
+MKT_GITEA_RELEASE_VERSION ?= $(MKT_PROJECT_VERSION)
 MKT_GITEA_RELEASE_COMMIT_TARGET ?= $(shell git rev-parse HEAD)
 MKT_GITEA_RELEASE_IS_DRAFT ?= false
 MKT_GITEA_RELEASE_BODY ?= 
@@ -26,4 +26,5 @@ mkt-gitea-release: tools/gitea-release/bin/gitea-release.sh
 tools/gitea-release/bin/gitea-release.sh:
 	mkdir -p tools/gitea-release/bin
 	curl --output tools/gitea-release/bin/gitea-release.sh https://forge.cadoles.com/Cadoles/Jenkins/raw/branch/master/resources/com/cadoles/gitea/gitea-release.sh
-	chmod +x tools/gitea-release/bin/gitea-release.sh
+	chmod +x tools/gitea-release/bin/gitea-release.sh
+	grep -qF -- "tools/" ".gitignore" 2>/dev/null || echo "tools/" >> ".gitignore"

tasks/version.mk

@@ -0,0 +1,34 @@
+MKT_PROJECT_BRANCH_NAME ?= $(shell git rev-parse --abbrev-ref HEAD | tr '[:upper:]' '[:lower:]' | sed -e 's/[-_ ]//g')
+
+ifeq ($(MKT_PROJECT_BRANCH_NAME),master)
+    MKT_PROJECT_VERSION_CHANNEL = stable
+else ifeq ($(MKT_PROJECT_BRANCH_NAME),staging)
+	MKT_PROJECT_VERSION_CHANNEL = testing
+else
+	MKT_PROJECT_VERSION_CHANNEL = $(MKT_PROJECT_BRANCH_NAME)
+endif
+
+
+ifeq ($(MKT_PROJECT_VERSION_CHANNEL),develop)
+    MKT_PROJECT_SHORT_VERSION_CHANNEL ?= dev
+else ifneq ($(filter $(MKT_PROJECT_VERSION_CHANNEL),testing staging),)
+	MKT_PROJECT_SHORT_VERSION_CHANNEL ?= tst
+else ifneq ($(filter $(MKT_PROJECT_VERSION_CHANNEL),stable master),)
+	MKT_PROJECT_SHORT_VERSION_CHANNEL ?= stb
+else
+	MKT_PROJECT_SHORT_VERSION_CHANNEL ?= $(shell echo "$(MKT_PROJECT_VERSION_CHANNEL)" | sed -e 's/[aeiouy]//g' | cut -c1-3)
+endif
+
+MKT_PROJECT_VERSION_DATE ?= $(shell date +%Y.%-m.%-d)
+MKT_PROJECT_VERSION_TIMESTAMP ?= $(shell date +%-H%M)
+
+MKT_PROJECT_VERSION ?= $(MKT_PROJECT_VERSION_DATE)-$(MKT_PROJECT_VERSION_CHANNEL).$(MKT_PROJECT_VERSION_TIMESTAMP).$(shell git rev-parse --short HEAD)
+MKT_PROJECT_SHORT_VERSION ?= $(MKT_PROJECT_VERSION_DATE)-$(MKT_PROJECT_SHORT_VERSION_CHANNEL).$(MKT_PROJECT_VERSION_TIMESTAMP)
+
+.PHONY: mkt-project-version
+mkt-project-version:
+	@echo $(MKT_PROJECT_VERSION)
+
+.PHONY: mkt-project-short-version
+mkt-project-short-version:
+	@echo $(MKT_PROJECT_SHORT_VERSION)