Filter milestones (#75)

* Create milestones data-source option

* Add documentation for the milestones option

Author: alexcanessa

docs/examples.md

@@ -35,6 +35,16 @@ Adding the flag `--data-source=commits` will change the source of the release no
 gren --data-source=commits
 ```
 
+### Milestones
+
+You can base your release notes on milestones.
+The way the script will _link_ the releases to your milestones is by the tag name, using the option `milestone-match`.
+ _e.g._ `Release {{tag_name}}` will match the milestone titles that have the relative tag name, in this case something like `Release 0.4.1`.
+
+ ```
+gren --data-source=milestones --milestone-match="v{{tag_name}}"
+ ``` 
+
 ### Release specific tags
 
 The flag `--tags` accepts one or two tags.

docs/options.md

@@ -16,18 +16,20 @@ To pass it to the `GithubReleaseNotes` class, in the [configuration file](#confi
 
 | Command | Options | Description | Default |
 | ------- | ------- | ----------- | ------- |
-| `api-url` | **Optional** | Override the GitHub API URL, allows **gren** to connect to a private [GHE](https://enterprise.github.com/) installation. _e.g. `https://my-enterprise-domain.com/api/v3`_ | `null` |
 | `username` | **Required** | The username of the repo _e.g. `github-tools`_ | `null` |
 | `repo` | **Required** | The repository name _e.g. `github-release-notes`_ | `null` |
+| `api-url` | **Optional** | Override the GitHub API URL, allows **gren** to connect to a private [GHE](https://enterprise.github.com/) installation. _e.g. `https://my-enterprise-domain.com/api/v3`_ | `null` |
 | `action`| `release` `changelog` | The **gren** action to run. _(see details below for changelog generator)_ | `release` |
 | `tags`    |   `0.1.0` `0.2.0,0.1.0` `all` |   A specific tag or the range of tags to build the release notes from. You can also specify `all` to write all releases. _(To override  existing releases use the --override flag)_ | `false` |
 | `ignore-labels` | `wont_fix` `wont_fix,duplicate` | Ignore the specified labels. | `false` |
 | `ignore-issues-with` | `wont_fix` `wont_fix,duplicate` | Ignore issues that contains one of the specified labels. | `false` |
-| `data-source` | `issues` `commits` | The informations you want to use to build release notes. | `issues` |
+| `data-source` | `issues` `commits` `milestones` | The informations you want to use to build release notes. For more informations about the `milestones` option, [have a look here]({{ "example#milestones" | relative_url }}) | `issues` |
+| `milestone-match` | **String** | The title that the script needs to match to link the release to the milestone. [See further details]({{ "example#milestones" | relative_url }}) | `null` |
 | `prefix` | **String** `e.g. v` | Add a prefix to the tag version. | `null` |
 | `override` | **Flag** | Override the release notes if existing. | `false` |
 | `include-messages` | `merge` `commits` `all` | Filter the messages added to the release notes. _Only used when `data-source` used is `commits` | `commits` |
 | `group-by` | `label` `{...}` | Group the issues using the labels as group headings. You can set custom headings for groups of labels. [See example]({{ "example#group-by" | relative_url }}) | `false` |
+| `only-milestones` | **Flag** | Add to the release bodies only the issues that have a milestone | `false` |
 
 ### Release options
 

src/gren.js

@@ -14,9 +14,10 @@ var configFile = utils.getConfigFromFile(process.cwd());
 
 var defaults = {
     tags: false,
-    timeWrap: 'latest', // || history
     changelogFilename: 'CHANGELOG.md',
     dataSource: 'issues', // || commits
+    onlyMilestones: false,
+    milestoneMatch: 'Release {{tag_name}}',
     draft: false,
     force: false,
     prefix: '',
@@ -508,6 +509,22 @@ function compareIssueLabels(ignoreLabels, labels) {
         }, true);
 }
 
+/**
+ * Filter the issue based on gren options and labels
+ *
+ * @since 0.9.0
+ * @private
+ *
+ * @param  {GithubReleaseNotes} gren
+ * @param  {Object} issue
+ *
+ * @return {Boolean}
+ */
+function filterIssue(gren, issue) {
+    return !issue.pull_request && compareIssueLabels(gren.options.ignoreIssuesWith, issue.labels) &&
+        !((gren.options.onlyMilestones || gren.options.dataSource === 'milestones') && !issue.milestone);
+}
+
 /**
  * Get all the closed issues from the current repo
  *
@@ -529,9 +546,7 @@ function getClosedIssues(gren, releaseRanges) {
     .then(function(response) {
         loaded();
 
-        var filteredIssues = response.data.filter(function(issue) {
-            return !issue.pull_request && compareIssueLabels(gren.options.ignoreIssuesWith, issue.labels);
-        });
+        var filteredIssues = response.data.filter(filterIssue.bind(null, gren));
 
         process.stdout.write(filteredIssues.length + ' issues found\n');
 
@@ -623,6 +638,31 @@ function groupBy(gren, issues) {
     return templateGroups(gren, groups);
 }
 
+/**
+ * Filter the issue based on the date range, or if is in the release
+ * milestone.
+ *
+ * @since 0.9.0
+ * @private
+ *
+ * @param  {GithubReleaseNotes} gren
+ * @param  {Array} range The release ranges
+ * @param  {Object} issue GitHub issue
+ *
+ * @return {Boolean}
+ */
+function filterBlockIssue(gren, range, issue) {
+    if (gren.options.dataSource === 'milestones') {
+        return gren.options.milestoneMatch.replace('{{tag_name}}', range[0].name) === issue.milestone.title;
+    }
+
+    return utils.isInRange(
+        Date.parse(issue.closed_at),
+        Date.parse(range[1].date),
+        Date.parse(range[0].date)
+    );
+}
+
 /**
  * Get the blocks of issues based on release dates
  *
@@ -641,14 +681,7 @@ function getIssueBlocks(gren, releaseRanges) {
         .then(function(issues) {
             return releaseRanges
                 .map(function(range) {
-                    var filteredIssues = issues.filter(function(issue) {
-                        return utils.isInRange(
-                            Date.parse(issue.closed_at),
-                            Date.parse(range[1].date),
-                            Date.parse(range[0].date)
-                        );
-                    });
-
+                    var filteredIssues = issues.filter(filterBlockIssue.bind(null, gren, range));
                     var body = (!range[0].body || gren.options.override) && groupBy(gren, filteredIssues);
 
                     return {
@@ -694,7 +727,7 @@ function createReleaseRanges(gren, releaseDates) {
     var range = 2;
     var sortedReleaseDates = sortReleasesByDate(releaseDates);
 
-    if (sortedReleaseDates.length === 1 || gren.options.timeWrap === 'history') {
+    if (sortedReleaseDates.length === 1) {
         sortedReleaseDates.push({
             id: 0,
             date: new Date(0)
@@ -720,7 +753,8 @@ function getReleaseBlocks(gren) {
     var loaded;
     var dataSource = {
         issues: getIssueBlocks,
-        commits: getCommitBlocks
+        commits: getCommitBlocks,
+        milestones: getIssueBlocks
     };
 
     return getListReleases(gren)
@@ -829,7 +863,6 @@ function GithubReleaseNotes(options) {
     this.options.ignoreIssuesWith = utils.convertStringToArray(this.options.ignoreIssuesWith);
     this.repo = null;
     this.issues = null;
-    this.isEditingLatestRelease = false;
 }
 
 /**