Merge 53af2de into 6050f20

git-chglog · Sep 27, 2019 · 577c54c · 577c54c
2 parents 6050f20 + 53af2de
commit 577c54c
Show file tree

Hide file tree

Showing 50 changed files with 7,527 additions and 83 deletions.
diff --git a/.chglog/config.yml b/.chglog/config.yml
@@ -18,10 +18,21 @@ options:
       perf: Performance Improvements
       refactor: Code Refactoring
   header:
-    pattern: "^(\\w*)\\:\\s(.*)$"
+    pattern: "^(\\w*)[\\[(\\w*)\\]]\\:\\s(.*)$"
     pattern_maps:
       - Type
+      - JiraIssueId
       - Subject
   notes:
     keywords:
       - BREAKING CHANGE
+  jira:
+    info:
+      username: u
+      token: p
+      url: https://jira.com
+    issue:
+      type_maps:
+        Task: fix
+        Story: feat
+      description_pattern: "<changelog>(.*)</changelog>"
diff --git a/Gopkg.lock b/Gopkg.lock
diff --git a/README.md b/README.md
@@ -480,6 +480,86 @@ See godoc [RenderData][doc-render-data] for available variables.
 > :memo: Even with styles that are not yet supported, it is possible to make ordinary CHANGELOG.
 
 
+## Jira Integration
+
+
+Jira is a popular project management tool. When a project uses Jira to track feature development and bug fixes,
+it may also want to generate change log based information stored in Jira. With embedding a Jira story id in git
+commit header, the git-chglog tool may automatically fetch data of the story from Jira, those data then can be 
+used to render the template.
+
+Take the following steps to add Jira integration:
+
+#### 1. Change the header parse pattern to recognize Jira issue id in the configure file.
+
+__Where Jira issue is identical Jira story.__
+
+The following is a sample pattern:
+
+  ```yaml
+  header:
+    pattern: "^(\\w*)[\\[(\\w*)\\]]\\:\\s(.*)$"
+    pattern_maps:
+      - Type
+      - JiraIssueId
+      - Subject
+  ```
+
+This sample pattern can match both forms of commit headers:
+
+* `feat: new feature of something`
+* `[JIRA-ID]: something`
+
+#### 2. Add Jira configuration to the configure file.
+
+The following is a sample:
+
+  ```yaml
+  jira:
+    info:
+      username: u
+      token: p
+      url: https://jira.com
+    issue:
+      type_maps:
+        Task: fix
+        Story: feat
+      description_pattern: "<changelog>(.*)</changelog>"
+  ```
+
+Here you need to define Jira URL, access username and token (password). If you don't want to
+write your Jira access credential in configure file, you may define them with environment variables:
+`JIRA_URL`, `JIRA_USERNAME` and `JIRA_TOKEN`.
+
+You also needs to define a issue type map. In above sample, Jira issue type `Task` will be
+mapped to `fix` and `Story` will be mapped to `feat`.
+
+As a Jira story's description could be very long, you might not want to include the entire
+description into change log. In that case, you may define `description_pattern` like above,
+so that only content embraced with `<changelog> ... </changelog>` will be included.
+
+#### 3. Update the template to show Jira data.
+
+In the template, if a commit contains a Jira issue id, then you may show Jira data. For example:
+
+```markdown
+{{ range .CommitGroups -}}
+### {{ .Title }}
+{{ range .Commits -}}
+- {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
+{{ if .JiraIssue }} {{ .JiraIssue.Description }}
+{{ end }}
+{{ end }}
+{{ end -}}
+```
+
+Within a `Commit`, the following Jira data can be used in template:
+
+* `.JiraIssue.Summary` - Summary of the Jira story
+* `.JiraIssue.Description` - Description of the Jira story
+* `.JiraIssue.Type` - Original type of the Jira story, and `.Type` will be mapped type.
+* `.JiraIssue.Labels` - A list of strings, each is a Jira label.
+
 
 
 ## FAQ

diff --git a/chglog.go b/chglog.go
@@ -16,23 +16,28 @@ import (
 
 // Options is an option used to process commits
 type Options struct {
-	Processor            Processor
-	NextTag              string              // Treat unreleased commits as specified tags (EXPERIMENTAL)
-	TagFilterPattern     string              // Filter tag by regexp
-	CommitFilters        map[string][]string // Filter by using `Commit` properties and values. Filtering is not done by specifying an empty value
-	CommitSortBy         string              // Property name to use for sorting `Commit` (e.g. `Scope`)
-	CommitGroupBy        string              // Property name of `Commit` to be grouped into `CommitGroup` (e.g. `Type`)
-	CommitGroupSortBy    string              // Property name to use for sorting `CommitGroup` (e.g. `Title`)
-	CommitGroupTitleMaps map[string]string   // Map for `CommitGroup` title conversion
-	HeaderPattern        string              // A regular expression to use for parsing the commit header
-	HeaderPatternMaps    []string            // A rule for mapping the result of `HeaderPattern` to the property of `Commit`
-	IssuePrefix          []string            // Prefix used for issues (e.g. `#`, `gh-`)
-	RefActions           []string            // Word list of `Ref.Action`
-	MergePattern         string              // A regular expression to use for parsing the merge commit
-	MergePatternMaps     []string            // Similar to `HeaderPatternMaps`
-	RevertPattern        string              // A regular expression to use for parsing the revert commit
-	RevertPatternMaps    []string            // Similar to `HeaderPatternMaps`
-	NoteKeywords         []string            // Keyword list to find `Note`. A semicolon is a separator, like `<keyword>:` (e.g. `BREAKING CHANGE`)
+	Processor                   Processor
+	NextTag                     string              // Treat unreleased commits as specified tags (EXPERIMENTAL)
+	TagFilterPattern            string              // Filter tag by regexp
+	CommitFilters               map[string][]string // Filter by using `Commit` properties and values. Filtering is not done by specifying an empty value
+	CommitSortBy                string              // Property name to use for sorting `Commit` (e.g. `Scope`)
+	CommitGroupBy               string              // Property name of `Commit` to be grouped into `CommitGroup` (e.g. `Type`)
+	CommitGroupSortBy           string              // Property name to use for sorting `CommitGroup` (e.g. `Title`)
+	CommitGroupTitleMaps        map[string]string   // Map for `CommitGroup` title conversion
+	HeaderPattern               string              // A regular expression to use for parsing the commit header
+	HeaderPatternMaps           []string            // A rule for mapping the result of `HeaderPattern` to the property of `Commit`
+	IssuePrefix                 []string            // Prefix used for issues (e.g. `#`, `gh-`)
+	RefActions                  []string            // Word list of `Ref.Action`
+	MergePattern                string              // A regular expression to use for parsing the merge commit
+	MergePatternMaps            []string            // Similar to `HeaderPatternMaps`
+	RevertPattern               string              // A regular expression to use for parsing the revert commit
+	RevertPatternMaps           []string            // Similar to `HeaderPatternMaps`
+	NoteKeywords                []string            // Keyword list to find `Note`. A semicolon is a separator, like `<keyword>:` (e.g. `BREAKING CHANGE`)
+	JiraUsername                string
+	JiraToken                   string
+	JiraUrl                     string
+	JiraTypeMaps                map[string]string
+	JiraIssueDescriptionPattern string
 }
 
 // Info is metadata related to CHANGELOG
@@ -100,6 +105,8 @@ func NewGenerator(config *Config) *Generator {
 		Bin: config.Bin,
 	})
 
+	jiraClient := NewJiraClient(config)
+
 	if config.Options.Processor != nil {
 		config.Options.Processor.Bootstrap(config)
 	}
@@ -111,7 +118,7 @@ func NewGenerator(config *Config) *Generator {
 		config:          config,
 		tagReader:       newTagReader(client, config.Options.TagFilterPattern),
 		tagSelector:     newTagSelector(),
-		commitParser:    newCommitParser(client, config),
+		commitParser:    newCommitParser(client, jiraClient, config),
 		commitExtractor: newCommitExtractor(config.Options),
 	}
 }