doc: updating readme

tomasbjerre · May 25, 2021 · 4b5ca4f · 4b5ca4f
1 parent 0c763af
commit 4b5ca4f
Show file tree

Hide file tree

Showing 7 changed files with 1,816 additions and 29 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -10,6 +10,7 @@ git:
 before_script:
   - git fetch origin master:master
   - git fetch origin test:test
+  - git fetch origin reverted-commits-test-branch:reverted-commits-test-branch
   - git pull
   - git log --graph --full-history --all --color --date=short --pretty=format:"%Cred%x09%h %Creset%ad%Cgreen%d %Creset %s %C(bold)(%an)%Creset"
 script:

diff --git a/README.md b/README.md
@@ -1,25 +1,38 @@
-# Git Changelog Lib [![Build Status](https://travis-ci.org/tomasbjerre/git-changelog-lib.svg?branch=master)](https://travis-ci.org/tomasbjerre/git-changelog-lib) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/se.bjurr.gitchangelog/git-changelog-lib/badge.svg)](https://maven-badges.herokuapp.com/maven-central/se.bjurr.gitchangelog/git-changelog-lib) [ ![Bintray](https://api.bintray.com/packages/tomasbjerre/tomasbjerre/se.bjurr.gitchangelog%3Agit-changelog-lib/images/download.svg) ](https://bintray.com/tomasbjerre/tomasbjerre/se.bjurr.gitchangelog%3Agit-changelog-lib/_latestVersion)
+# Git Changelog Lib
 
-This is a library for generating a changelog, or releasenotes, from a GIT repository. It can also be run as a standalone program, Gradle plugin, Maven plugin or Jenkins plugin.
+[![Build Status](https://travis-ci.org/tomasbjerre/git-changelog-lib.svg?branch=master)](https://travis-ci.org/tomasbjerre/git-changelog-lib)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/se.bjurr.gitchangelog/git-changelog-lib/badge.svg)](https://maven-badges.herokuapp.com/maven-central/se.bjurr.gitchangelog/git-changelog-lib)
 
-It is fully configurable with a [Mustache (Handlebars)](https://github.com/jknack/handlebars.java) template. That can:
+This is a library that can:
 
- * Be stored to file, like `CHANGELOG.md`. There are some templates used for testing available [here](/src/test/resources/templatetest).
- * Or just rendered to a `String`.
+- Generate a changelog, or releasenotes, from a GIT repository.
+- Determine next version, based on format of commits since last release.
 
-It can integrate with Jira and/or GitHub to retrieve the title of issues.
+It is fully configurable with a [Mustache (Handlebars)](https://github.com/jknack/handlebars.java) template and [helpers](#Helpers).
+
+The changelog can:
+
+- Be stored to file, like `CHANGELOG.md`. There are some templates used for testing available [here](/src/test/resources/templatetest).
+- Or, just rendered to a `String`.
 
-The [changelog](/CHANGELOG.md) of this project is automatically generated with [this template](/changelog.mustache).
+It can integrate with Jira and/or GitHub to retrieve the title of issues.
 
 ## Usage
+
 This software can be used:
- * With a [Gradle plugin](https://github.com/tomasbjerre/git-changelog-gradle-plugin).
- * With a [Maven plugin](https://github.com/tomasbjerre/git-changelog-maven-plugin).
- * With a [Jenkins plugin](https://github.com/jenkinsci/git-changelog-plugin).
- * From [command line](https://github.com/tomasbjerre/git-changelog-command-line).
- * As a library [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22git-changelog-lib%22).
 
-Here is an example template. 
+- With a [Gradle plugin](https://github.com/tomasbjerre/git-changelog-gradle-plugin).
+- With a [Maven plugin](https://github.com/tomasbjerre/git-changelog-maven-plugin).
+- With a [Jenkins plugin](https://github.com/jenkinsci/git-changelog-plugin).
+- From [command line](https://github.com/tomasbjerre/git-changelog-command-line).
+- As a library [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22git-changelog-lib%22).
+
+There are examples of different templates [in the code](/src/test/resources) that are used for testing.
+
+### Template - Simple
+
+Here is an example template.
+
 ```hbs
 # Changelog
 
@@ -44,7 +57,7 @@ Changelog for {{ownerName}} {{repoName}}.
 **{{{messageTitle}}}**
 
 {{#messageBodyItems}}
- * {{.}} 
+ * {{.}}
 {{/messageBodyItems}}
 
 [{{hash}}](https://github.com/{{ownerName}}/{{repoName}}/commit/{{hash}}) {{authorName}} *{{commitTime}}*
@@ -55,9 +68,160 @@ Changelog for {{ownerName}} {{repoName}}.
 {{/tags}}
 ```
 
-There are some examples [here](/examples) that are ready to use.
+### Template - Conventional
+
+If you are using [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) you can use built in [helpers](/src/main/java/se/bjurr/gitchangelog/api/helpers) to produce a nice changelog. You can add your own helpers (using Javascript or Java) as described [here](https://github.com/jknack/handlebars.java).
+
+```hbs
+{{#tags}}
+{{#ifReleaseTag .}}
+## [{{name}}](https://gitlab.com/html-validate/html-validate/compare/{{name}}) ({{tagDate .}})
+
+  {{#ifContainsType commits type='feat'}}
+### Features
+
+    {{#commits}}
+      {{#ifCommitType . type='feat'}}
+ - {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://gitlab.com/html-validate/html-validate/commit/{{hashFull}}))
+      {{/ifCommitType}}
+    {{/commits}}
+  {{/ifContainsType}}
+
+  {{#ifContainsType commits type='fix'}}
+### Bug Fixes
+
+    {{#commits}}
+      {{#ifCommitType . type='fix'}}
+ - {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://gitlab.com/html-validate/html-validate/commit/{{hashFull}}))
+      {{/ifCommitType}}
+    {{/commits}}
+  {{/ifContainsType}}
+
+{{/ifReleaseTag}}
+{{/tags}}
+```
+
+## Helpers
+
+Some [helpers](/src/main/java/se/bjurr/gitchangelog/api/helpers) are implemented in this library. And users can also add more helpers as described in [Handlebars](https://github.com/jknack/handlebars.java).
+
+### `ifReleaseTag <Tag>`
+
+Conditional, renders a block if given `Tag` matches release-tag.
+
+```hbs
+{{#tags}}
+ {{#ifReleaseTag .}}
+  "{{.}}" is a release tag
+ {{/ifReleaseTag}}
+{{/tags}}
+```
+
+### `tagDate <Tag>`
+
+Renders date of `Tag` on format `YYYY-MM-DD`.
+
+```hbs
+{{#tags}}
+ {{tagDate .}}
+{{/tags}}
+```
+
+### `ifContainsType <List<Commit>>`
 
-There are also different variations [here](/src/test/resources/templates) that are used for testing.
+Conditional, renders a block if given `List<Commits>` contains given `type`.
+
+```hbs
+{{#ifContainsType commits type="fix"}}
+  commits contains fixes
+{{/ifContainsType}}
+```
+
+### `commitDate <Commit>`
+
+Renders date of `Commit` on format `YYYY-MM-DD`.
+
+```hbs
+{{#commits}}
+ {{commitDate .}}
+{{/commits}}
+```
+
+### `commitDescription <Commit>`
+
+Renders description of `Commit`.
+
+```hbs
+{{#commits}}
+ {{commitDescription .}}
+{{/commits}}
+```
+
+### `revertedCommit <Commit>`
+
+Renders reverted commit refered to by `Commit`.
+
+```hbs
+{{#commits}}
+ {{revertedCommit .}}
+{{/commits}}
+```
+
+### `ifCommitType <Commit> type="<type>"`
+
+Conditional, renders a block if given `Commit` is of `type`.
+
+```hbs
+{{#commits}}
+ {{#ifCommitType . type="fix"}} is type fix {{/ifCommitType}}
+{{/commits}}
+```
+
+### `ifCommitScope <Commit> scope="utils"`
+
+Conditional, renders a block if given `Commit` has `scope`.
+
+```hbs
+{{#commits}}
+ {{#ifCommitScope . scope="utils"}} is scope utils {{/ifCommitScope}}
+{{/commits}}
+```
+
+### `eachCommitScope <Commit>`
+
+Renders block for each `scope` in `Commit`.
+
+```hbs
+{{#commits}}
+ {{#eachCommitScope .}}
+  scope: {{.}}
+ {{/eachCommitScope}}
+{{/commits}}
+```
+
+### `eachCommitRefs <Commit>`
+
+Renders block for each `refs` in `Commit`.
+
+```hbs
+{{#commits}}
+ {{#eachCommitRefs .}}
+  references issue: {{.}}
+ {{/eachCommitRefs}}
+{{/commits}}
+```
+
+### `eachCommitFixes <Commit>`
+
+Renders block for each `fixes` in `Commit`.
+
+```hbs
+{{#commits}}
+ {{#eachCommitFixes .}}
+  fixes issue: {{.}}
+ {{/eachCommitFixes}}
+{{/commits}}
+```
 
 ## Context
 
@@ -278,18 +442,7 @@ It has a [builder](/src/main/java/se/bjurr/gitchangelog/api/GitChangelogApi.java
    .withFromCommit(ZERO_COMMIT)
    .withToRef("refs/heads/master")
    .withTemplatePath("changelog.mustache")
-   .toFile("CHANGELOG.md");
-```
-
-It can also create releasenotes. If you are using git flow it may look like this.
-
-```java
-  gitChangelogApiBuilder()
-   .withFromRef("refs/heads/dev")
-   .withToRef("refs/heads/master")
-   .withTemplatePath("releasenotes.mustache")
-   .toStdout();
+   .render();
 ```
 
-Settings can be supplied with a JSON config ([documented here](/src/main/java/se/bjurr/gitchangelog/internal/settings/Settings.java)).
-
+Settings can be supplied with the build or from a JSON config ([documented here](/src/main/java/se/bjurr/gitchangelog/internal/settings/Settings.java)).
diff --git a/src/test/java/se/bjurr/gitchangelog/api/HandlebarsHelperTest.java b/src/test/java/se/bjurr/gitchangelog/api/HandlebarsHelperTest.java
@@ -41,4 +41,15 @@ public void testThatBuiltInHelperMethodsCanBeUsed() throws Exception {
 
     ApprovalsWrapper.verify(given);
   }
+
+  @Test
+  public void testThatConventionalChangelogCanBeRendered() throws Exception {
+    final GitChangelogApi given =
+        this.baseBuilder //
+            .withFromCommit("ed95e6a") //
+            .withToCommit("d346292") //
+            .withTemplatePath("templatetest/testThatConventionalChangelogCanBeRendered.mustache");
+
+    ApprovalsWrapper.verify(given);
+  }
 }
diff --git a/.../gitchangelog/api/HandlebarsHelperTest.testThatBuiltInHelperMethodsCanBeUsed.approved.txt b/.../gitchangelog/api/HandlebarsHelperTest.testThatBuiltInHelperMethodsCanBeUsed.approved.txt
@@ -38,6 +38,7 @@ Commits:
 
  {{#ifCommitType . type="revert"}} is type revert {{/ifCommitType}}
  {{#ifCommitType . type="fix"}} is type fix {{/ifCommitType}}
+ {{#ifCommitType . type=""}} commit has no type {{/ifCommitType}}
 
  {{#ifCommitScope . scope="utils"}} is scope utils {{/ifCommitScope}}
 
@@ -141,6 +142,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
   is type revert 
 
+
 
 
 
@@ -157,6 +159,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
 
   is type fix 
+
 
   is scope utils 
 
@@ -175,6 +178,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
 
 
+
 
   is scope utils 
 
@@ -191,6 +195,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
 
 
+  commit has no type 
 
 
 
@@ -206,6 +211,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
 
 
+  commit has no type 
 
 
 
@@ -221,6 +227,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
 
   is type fix 
+
 
 
 
@@ -236,6 +243,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
 
 
+  commit has no type 
 
 
 
@@ -251,6 +259,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
 
 
+  commit has no type 
 
 
 
@@ -266,6 +275,7 @@ This reverts commit 1edc0d71eccce51abfb5f62fdddfbe73913785f5.
 
 
   is type fix 
+