- expand configuration specification by offering sorting by alternative properties -> title instead of mergedAt.

- add more testcases to cover the new sort orders
  - FIX https://github.com/mikepenz/release-changelog-builder-action/issues/757

README.md

@@ -327,7 +327,9 @@ Table of descriptions for the `configuration.json` options to configure the resu
 | category.exclude_labels     | Similar to `labels`, an array of labels to match PRs against, but if a match occurs the PR is excluded from this category.                                                                                                         |
 | category.exhaustive         | Will require all labels defined within this category to be present on the matching PR.                                                                                                                                             |
 | ignore_labels               | An array of labels, to match pull request labels against. If any PR label overlaps, the pull request will be ignored from the changelog. This takes precedence over category labels                                                |
-| sort                        | The sort order of pull requests. [ASC, DESC]                                                                                                                                                                                       |
+| sort                        | A `sort` specification, offering the ability to define sort order and property.                                                                                                                                                    |
+| sort.order                  | The sort order. Allowed values: `ASC`, `DESC`                                                                                                                                                                                      |
+| sort.on_property            | The property to sort on. Allowed values: `mergedAt`, `title`                                                                                                                                                                       |
 | template                    | Specifies the global template to pick for creating the changelog. See [Template placeholders](#template-placeholders) for possible values                                                                                          |
 | pr_template                 | Defines the per pull request template. See [PR Template placeholders](#pr-template-placeholders) for possible values                                                                                                               |
 | empty_template              | Template to pick if no changes are detected. See [Template placeholders](#template-placeholders) for possible values                                                                                                               |

__tests__/releaseNotes.test.ts

@@ -172,6 +172,54 @@ it('Should match ordered DESC', async () => {
   )
 })
 
+it('Should match ordered by title ASC', async () => {
+  const configuration = resolveConfiguration(
+    '',
+    'configs_test/configuration_sort_title_asc.json'
+  )
+  const releaseNotes = new ReleaseNotes(octokit, {
+    owner: 'mikepenz',
+    repo: 'release-changelog-builder-action',
+    fromTag: 'v0.3.0',
+    toTag: 'v0.5.0',
+    includeOpen: false,
+    failOnError: false,
+    fetchReviewers: false,
+    commitMode: false,
+    configuration
+  })
+
+  const changeLog = await releaseNotes.pull()
+  console.log(changeLog)
+  expect(changeLog).toStrictEqual(
+    `## 🚀 Features\n\nEnhanced action logs\nImprove README\nImproved configuration failure handling\nImproved defaults if no configuration is provided\nIntroduce additional placeholders [milestone, labels, assignees, reviewers]\n\n## 🐛 Fixes\n\nImproved handling for non existing tags\n\n`
+  )
+})
+
+it('Should match ordered by title DESC', async () => {
+  const configuration = resolveConfiguration(
+    '',
+    'configs_test/configuration_sort_title_desc.json'
+  )
+  const releaseNotes = new ReleaseNotes(octokit, {
+    owner: 'mikepenz',
+    repo: 'release-changelog-builder-action',
+    fromTag: 'v0.3.0',
+    toTag: 'v0.5.0',
+    includeOpen: false,
+    failOnError: false,
+    fetchReviewers: false,
+    commitMode: false,
+    configuration
+  })
+
+  const changeLog = await releaseNotes.pull()
+  console.log(changeLog)
+  expect(changeLog).toStrictEqual(
+    `## 🚀 Features\n\nIntroduce additional placeholders [milestone, labels, assignees, reviewers]\nImproved defaults if no configuration is provided\nImproved configuration failure handling\nImprove README\nEnhanced action logs\n\n## 🐛 Fixes\n\nImproved handling for non existing tags\n\n`
+  )
+})
+
 it('Should ignore PRs not merged into develop branch', async () => {
   const configuration = resolveConfiguration(
     '',

configs_test/configuration_desc.json

@@ -1,5 +1,8 @@
 {
-    "sort": "DESC",
+    "sort": {
+        "order": "DESC",
+        "on_property": "mergedAt"
+    },
     "pr_template": "${{NUMBER}}",
     "max_pull_requests": 1000,
     "max_back_track_time_days": 1000

configs_test/configuration_sort_title_asc.json

@@ -0,0 +1,9 @@
+{
+    "sort": {
+        "order": "ASC",
+        "on_property": "title"
+    },
+    "pr_template": "${{TITLE}}",
+    "max_pull_requests": 1000,
+    "max_back_track_time_days": 1000
+}

configs_test/configuration_sort_title_desc.json

@@ -0,0 +1,9 @@
+{
+    "sort": {
+        "order": "DESC",
+        "on_property": "title"
+    },
+    "pr_template": "${{TITLE}}",
+    "max_pull_requests": 1000,
+    "max_back_track_time_days": 1000
+}

dist/index.js

@@ -153,7 +153,11 @@ exports.DefaultConfiguration = {
     max_pull_requests: 200,
     max_back_track_time_days: 365,
     exclude_merge_branches: [],
-    sort: 'ASC',
+    sort: {
+        // defines the sorting logic for PRs
+        order: 'ASC',
+        on_property: 'mergedAt' // the property to sort on. (mergedAt falls back to createdAt)
+    },
     template: '${{CHANGELOG}}',
     pr_template: '- ${{TITLE}}\n   - PR: #${{NUMBER}}',
     empty_template: '- no changes',
@@ -449,7 +453,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.sortPullRequests = exports.PullRequests = void 0;
+exports.compare = exports.sortPullRequests = exports.PullRequests = void 0;
 const core = __importStar(__nccwpck_require__(2186));
 const moment_1 = __importDefault(__nccwpck_require__(9623));
 class PullRequests {
@@ -499,7 +503,7 @@ class PullRequests {
                             core.warning(`⚠️ Reached 'maxPullRequests' count ${maxPullRequests}`);
                         }
                         // bail out early to not keep iterating on PRs super old
-                        return sortPullRequests(mergedPRs, true);
+                        return sortPrs(mergedPRs);
                     }
                 }
             }
@@ -510,7 +514,7 @@ class PullRequests {
                 }
                 finally { if (e_1) throw e_1.error; }
             }
-            return sortPullRequests(mergedPRs, true);
+            return sortPrs(mergedPRs);
         });
     }
     getOpen(owner, repo, maxPullRequests) {
@@ -538,7 +542,7 @@ class PullRequests {
                             core.warning(`⚠️ Reached 'maxPullRequests' count ${maxPullRequests}`);
                         }
                         // bail out early to not keep iterating on PRs super old
-                        return sortPullRequests(openPrs, true);
+                        return sortPrs(openPrs);
                     }
                 }
             }
@@ -549,7 +553,7 @@ class PullRequests {
                 }
                 finally { if (e_2) throw e_2.error; }
             }
-            return sortPullRequests(openPrs, true);
+            return sortPrs(openPrs);
         });
     }
     getReviewers(owner, repo, pr) {
@@ -582,36 +586,55 @@ class PullRequests {
     }
 }
 exports.PullRequests = PullRequests;
-function sortPullRequests(pullRequests, ascending) {
+function sortPrs(pullRequests) {
-    if (ascending) {
+    return sortPullRequests(pullRequests, {
+        order: 'ASC',
+        on_property: 'mergedAt'
+    });
+}
+function sortPullRequests(pullRequests, sort) {
+    let sortConfig;
+    // legacy handling to support string sort config
+    if (typeof sort === 'string') {
+        let order = 'ASC';
+        if (sort.toUpperCase() === 'DESC')
+            order = 'DESC';
+        sortConfig = { order, on_property: 'mergedAt' };
+    }
+    else {
+        sortConfig = sort;
+    }
+    if (sortConfig.order === 'ASC') {
         pullRequests.sort((a, b) => {
-            const aa = a.mergedAt || a.createdAt;
+            return compare(a, b, sortConfig);
-            const bb = b.mergedAt || b.createdAt;
-            if (aa.isBefore(bb)) {
-                return -1;
-            }
-            else if (bb.isBefore(aa)) {
-                return 1;
-            }
-            return 0;
         });
     }
     else {
         pullRequests.sort((b, a) => {
-            const aa = a.mergedAt || a.createdAt;
+            return compare(a, b, sortConfig);
-            const bb = b.mergedAt || b.createdAt;
-            if (aa.isBefore(bb)) {
-                return -1;
-            }
-            else if (bb.isBefore(aa)) {
-                return 1;
-            }
-            return 0;
         });
     }
     return pullRequests;
 }
 exports.sortPullRequests = sortPullRequests;
+function compare(a, b, sort) {
+    if (sort.on_property === 'mergedAt') {
+        const aa = a.mergedAt || a.createdAt;
+        const bb = b.mergedAt || b.createdAt;
+        if (aa.isBefore(bb)) {
+            return -1;
+        }
+        else if (bb.isBefore(aa)) {
+            return 1;
+        }
+        return 0;
+    }
+    else {
+        // only else for now `label`
+        return a.title.localeCompare(b.title);
+    }
+}
+exports.compare = compare;
 // helper function to add a special open label to prs not merged.
 function attachSpeciaLabels(status, labels) {
     labels.add(`--rcba-${status}`);
@@ -1345,8 +1368,7 @@ function buildChangelog(prs, options) {
     // sort to target order
     const config = options.configuration;
     const sort = config.sort || configuration_1.DefaultConfiguration.sort;
-    const sortAsc = sort.toUpperCase() === 'ASC';
+    prs = (0, pullRequests_1.sortPullRequests)(prs, sort);
-    prs = (0, pullRequests_1.sortPullRequests)(prs, sortAsc);
     core.info(`ℹ️ Sorted all pull requests ascending: ${sort}`);
     // drop duplicate pull requests
     if (config.duplicate_filter !== undefined) {
@@ -1369,7 +1391,7 @@ function buildChangelog(prs, options) {
             deduplicatedPRs.push(...unmatched); // add all unmatched PRs to map
             const removedElements = prs.length - deduplicatedPRs.length;
             core.info(`ℹ️ Removed ${removedElements} pull requests during deduplication`);
-            prs = (0, pullRequests_1.sortPullRequests)(deduplicatedPRs, sortAsc); // resort deduplicatedPRs
+            prs = (0, pullRequests_1.sortPullRequests)(deduplicatedPRs, sort); // resort deduplicatedPRs
         }
         else {
             core.warning(`⚠️ Configured \`duplicate_filter\` invalid.`);

src/configuration.ts

@@ -3,7 +3,7 @@ export interface Configuration {
   max_pull_requests: number
   max_back_track_time_days: number
   exclude_merge_branches: string[]
-  sort: string // "ASC" or "DESC"
+  sort: Sort | string // "ASC" or "DESC"
   template: string
   pr_template: string
   empty_template: string
@@ -23,6 +23,11 @@ export interface Category {
   exhaustive?: boolean // requires all labels to be present in the PR
 }
 
+export interface Sort {
+  order: 'ASC' | 'DESC' // the sorting order
+  on_property: 'mergedAt' | 'title' // the property to sort on. (mergedAt falls back to createdAt)
+}
+
 export interface Regex {
   pattern: string // the regex pattern to match
   flags?: string // the regex flag to use for RegExp
@@ -55,7 +60,11 @@ export const DefaultConfiguration: Configuration = {
   max_pull_requests: 200, // the amount of pull requests to process
   max_back_track_time_days: 365, // allow max of 365 days back to check up on pull requests
   exclude_merge_branches: [], // branches to exclude from counting as PRs (e.g. YourOrg/qa, YourOrg/main)
-  sort: 'ASC', // sorting order for filling the changelog (ASC or DESC) supported
+  sort: {
+    // defines the sorting logic for PRs
+    order: 'ASC', // the sorting order
+    on_property: 'mergedAt' // the property to sort on. (mergedAt falls back to createdAt)
+  },
   template: '${{CHANGELOG}}', // the global template to host the changelog
   pr_template: '- ${{TITLE}}\n   - PR: #${{NUMBER}}', // the per PR template to pick
   empty_template: '- no changes', // the template to use if no pull requests are found

src/pullRequests.ts

@@ -2,6 +2,7 @@ import * as core from '@actions/core'
 import {Octokit, RestEndpointMethodTypes} from '@octokit/rest'
 import {Unpacked} from './utils'
 import moment from 'moment'
+import {Sort} from './configuration'
 
 export interface PullRequestInfo {
   number: number
@@ -89,11 +90,11 @@ export class PullRequests {
         }
 
         // bail out early to not keep iterating on PRs super old
-        return sortPullRequests(mergedPRs, true)
+        return sortPrs(mergedPRs)
       }
     }
 
-    return sortPullRequests(mergedPRs, true)
+    return sortPrs(mergedPRs)
   }
 
   async getOpen(
@@ -125,11 +126,11 @@ export class PullRequests {
         }
 
         // bail out early to not keep iterating on PRs super old
-        return sortPullRequests(openPrs, true)
+        return sortPrs(openPrs)
       }
     }
 
-    return sortPullRequests(openPrs, true)
+    return sortPrs(openPrs)
   }
 
   async getReviewers(
@@ -155,36 +156,60 @@ export class PullRequests {
   }
 }
 
+function sortPrs(pullRequests: PullRequestInfo[]): PullRequestInfo[] {
+  return sortPullRequests(pullRequests, {
+    order: 'ASC',
+    on_property: 'mergedAt'
+  })
+}
+
 export function sortPullRequests(
   pullRequests: PullRequestInfo[],
-  ascending: Boolean
+  sort: Sort | string
 ): PullRequestInfo[] {
-  if (ascending) {
+  let sortConfig: Sort
+
+  // legacy handling to support string sort config
+  if (typeof sort === 'string') {
+    let order: 'ASC' | 'DESC' = 'ASC'
+    if (sort.toUpperCase() === 'DESC') order = 'DESC'
+    sortConfig = {order, on_property: 'mergedAt'}
+  } else {
+    sortConfig = sort
+  }
+
+  if (sortConfig.order === 'ASC') {
     pullRequests.sort((a, b) => {
-      const aa = a.mergedAt || a.createdAt
+      return compare(a, b, sortConfig)
-      const bb = b.mergedAt || b.createdAt
-      if (aa.isBefore(bb)) {
-        return -1
-      } else if (bb.isBefore(aa)) {
-        return 1
-      }
-      return 0
     })
   } else {
     pullRequests.sort((b, a) => {
-      const aa = a.mergedAt || a.createdAt
+      return compare(a, b, sortConfig)
-      const bb = b.mergedAt || b.createdAt
-      if (aa.isBefore(bb)) {
-        return -1
-      } else if (bb.isBefore(aa)) {
-        return 1
-      }
-      return 0
     })
   }
   return pullRequests
 }
 
+export function compare(
+  a: PullRequestInfo,
+  b: PullRequestInfo,
+  sort: Sort
+): number {
+  if (sort.on_property === 'mergedAt') {
+    const aa = a.mergedAt || a.createdAt
+    const bb = b.mergedAt || b.createdAt
+    if (aa.isBefore(bb)) {
+      return -1
+    } else if (bb.isBefore(aa)) {
+      return 1
+    }
+    return 0
+  } else {
+    // only else for now `label`
+    return a.title.localeCompare(b.title)
+  }
+}
+
 // helper function to add a special open label to prs not merged.
 function attachSpeciaLabels(
   status: 'open' | 'merged',

src/transform.ts

@@ -15,8 +15,7 @@ export function buildChangelog(
   // sort to target order
   const config = options.configuration
   const sort = config.sort || DefaultConfiguration.sort
-  const sortAsc = sort.toUpperCase() === 'ASC'
+  prs = sortPullRequests(prs, sort)
-  prs = sortPullRequests(prs, sortAsc)
   core.info(`ℹ️ Sorted all pull requests ascending: ${sort}`)
 
   // drop duplicate pull requests
@@ -44,7 +43,7 @@ export function buildChangelog(
       core.info(
         `ℹ️ Removed ${removedElements} pull requests during deduplication`
       )
-      prs = sortPullRequests(deduplicatedPRs, sortAsc) // resort deduplicatedPRs
+      prs = sortPullRequests(deduplicatedPRs, sort) // resort deduplicatedPRs
     } else {
       core.warning(`⚠️ Configured \`duplicate_filter\` invalid.`)
     }