Docs (#5)

* fix: Update task key and enhance work item fetching logic; add JSON output functionality

* fix: Update task key and add HTML output for release notes

* fix: Update output file names in task.json and README.md for consistency

* fix: Update output section in README.md to clarify default markdown and HTML templates

* fix: Correct output section header and improve local testing instructions in README.md

Author: IeuanWalker

.gitignore

@@ -225,3 +225,4 @@ Tools/**/*.js.map
 
 !jest.config.js
 output/release-notes.md
+output/release-notes.html

CommitRangeReleaseNotesTask/task/dist/.taskkey

@@ -1 +1 @@
-30435434-173e-4a63-8c43-9a886bd70284
+8540612f-cbf9-4737-b3b4-6f49e7425db8

CommitRangeReleaseNotesTask/task/dist/main.js

@@ -15,6 +15,7 @@ const fs = require("fs");
 const CommitUtils_1 = require("./utils/CommitUtils");
 const PRUtils_1 = require("./utils/PRUtils");
 const TemplateUtils_1 = require("./utils/TemplateUtils");
+const JsonOutput_1 = require("./utils/JsonOutput");
 (0, TemplateUtils_1.registerHelpers)();
 function GenerateReleaseNotes(startCommit, endCommit, outputFileMarkdown, outputFileHtml, repoRoot, systemAccessToken, project, apiUrl, repositoryId, templateFileMarkdown, templateFileHtml) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -157,7 +158,7 @@ function GenerateReleaseNotes(startCommit, endCommit, outputFileMarkdown, output
             repositoryId,
             project
         };
-        //printJson(releaseData);
+        (0, JsonOutput_1.printJson)(releaseData);
         (0, TemplateUtils_1.GenerateMarkdownReleaseNotes)(releaseData, outputFileMarkdown, templateFileMarkdown);
         (0, TemplateUtils_1.GenerateHtmlReleaseNotes)(releaseData, outputFileHtml, templateFileHtml);
     });

CommitRangeReleaseNotesTask/task/dist/utils/TemplateUtils.js

@@ -28,7 +28,6 @@ const Handlebars = __importStar(require("handlebars"));
 const fs = require("fs");
 const path = require("path");
 const tl = require("azure-pipelines-task-lib/task");
-const JsonOutput_1 = require("./JsonOutput");
 function registerHelpers() {
     // GroupBy helper
     Handlebars.registerHelper('groupBy', function (items, field, options) {
@@ -104,72 +103,45 @@ function GenerateMarkdownReleaseNotes(data, outputFile, templateFile) {
 }
 exports.GenerateMarkdownReleaseNotes = GenerateMarkdownReleaseNotes;
 function GenerateHtmlReleaseNotes(data, outputFile, templateFile) {
-    var _a, _b;
     console.log('Starting HTML release notes generation...');
     // Convert PR descriptions from markdown to HTML
     const { marked } = require('marked');
-    console.log(`Found ${((_a = data.pullRequests) === null || _a === void 0 ? void 0 : _a.length) || 0} pull requests`);
-    console.log(`Found ${((_b = data.commits) === null || _b === void 0 ? void 0 : _b.length) || 0} commits`);
     // Convert descriptions in the pullRequests array
     if (Array.isArray(data.pullRequests) && data.pullRequests.length > 0) {
-        console.log(`Processing ${data.pullRequests.length} pull requests`);
         data.pullRequests = data.pullRequests.map(pr => {
-            console.log(`Checking PR ${pr.id}: has description = ${!!pr.description}, type = ${typeof pr.description}`);
             if (pr && pr.description != null && typeof pr.description === 'string' && pr.description.trim() !== '') {
-                console.log(`Converting PR ${pr.id} description from markdown to HTML`);
-                console.log(`Original (first 200 chars): ${pr.description.substring(0, 200)}`);
                 try {
                     const converted = marked(pr.description);
-                    console.log(`Converted (first 200 chars): ${converted.substring(0, 200)}`);
                     return Object.assign(Object.assign({}, pr), { description: converted });
                 }
                 catch (error) {
                     console.warn(`Failed to convert markdown for PR: ${pr.id || 'unknown'}`, error);
                     return pr;
                 }
             }
-            else {
-                console.log(`Skipping PR ${pr.id} - no valid description`);
-            }
             return pr;
         });
     }
-    else {
-        console.log('No pull requests to process');
-    }
     // Convert descriptions in commits.pullRequest objects
     if (Array.isArray(data.commits) && data.commits.length > 0) {
-        console.log(`Processing ${data.commits.length} commits`);
         data.commits = data.commits.map(commit => {
             if (commit && commit.pullRequest) {
-                console.log(`Checking commit PR ${commit.pullRequest.id}: has description = ${!!commit.pullRequest.description}, type = ${typeof commit.pullRequest.description}`);
                 if (commit.pullRequest.description != null &&
                     typeof commit.pullRequest.description === 'string' &&
                     commit.pullRequest.description.trim() !== '') {
-                    console.log(`Converting commit PR ${commit.pullRequest.id} description from markdown to HTML`);
-                    console.log(`Original (first 200 chars): ${commit.pullRequest.description.substring(0, 200)}`);
                     try {
                         const converted = marked(commit.pullRequest.description);
-                        console.log(`Converted (first 200 chars): ${converted.substring(0, 200)}`);
                         return Object.assign(Object.assign({}, commit), { pullRequest: Object.assign(Object.assign({}, commit.pullRequest), { description: converted }) });
                     }
                     catch (error) {
                         console.warn(`Failed to convert markdown for commit PR: ${commit.pullRequest.id || 'unknown'}`, error);
                         return commit;
                     }
                 }
-                else {
-                    console.log(`Skipping commit PR ${commit.pullRequest.id} - no valid description`);
-                }
             }
             return commit;
         });
     }
-    else {
-        console.log('No commits to process');
-    }
-    console.log('Markdown conversion complete, proceeding with template generation...');
-    (0, JsonOutput_1.printJson)(data);
     // Get template
     let template;
     try {

CommitRangeReleaseNotesTask/task/dist/utils/WorkItemUtils.js

@@ -13,13 +13,6 @@ exports.getWorkItem = void 0;
 function getWorkItem(workItemId, apiUrl, project, accessToken) {
     var _a, _b, _c, _d;
     return __awaiter(this, void 0, void 0, function* () {
-        const fields = [
-            "System.Title",
-            "System.WorkItemType",
-            "System.AssignedTo",
-            "System.Description"
-        ];
-        // fields=${fields.join(',')}&
         const url = `${apiUrl}/${project}/_apis/wit/workitems/${workItemId}?api-version=7.1&$expand=ALL`;
         console.log(`Fetching work item ${workItemId} from ${url}`);
         try {

CommitRangeReleaseNotesTask/task/task.json

@@ -33,15 +33,15 @@
       "name": "outputFileMarkdown",
       "type": "filePath",
       "label": "Output File - Markdown",
-      "defaultValue": "$(Build.ArtifactStagingDirectory)/ReleaseNotes.md",
+      "defaultValue": "$(Build.ArtifactStagingDirectory)/release-notes.md",
       "required": true,
       "helpMarkDown": "Path where the generated release notes will be saved"
     },
     {
       "name": "outputFileHtml",
       "type": "filePath",
       "label": "Output File - HTML",
-      "defaultValue": "$(Build.ArtifactStagingDirectory)/ReleaseNotes.html",
+      "defaultValue": "$(Build.ArtifactStagingDirectory)/release-notes.html",
       "required": true,
       "helpMarkDown": "Path where the generated release notes will be saved"
     },

CommitRangeReleaseNotesTask/task/utils/WorkItemUtils.ts

@@ -36,14 +36,6 @@ export async function getWorkItem(
     project: string,
     accessToken: string
 ): Promise<WorkItem | null> {
-    const fields = [
-        "System.Title",
-        "System.WorkItemType",
-        "System.AssignedTo",
-        "System.Description"
-    ];
-
-    // fields=${fields.join(',')}&
     const url = `${apiUrl}/${project}/_apis/wit/workitems/${workItemId}?api-version=7.1&$expand=ALL`;
     console.log(`Fetching work item ${workItemId} from ${url}`);
 

README.md

@@ -24,7 +24,8 @@ The extension analyses Git commits in a specified range, looking for merge commi
   inputs:
     startCommit: 'v1.0.0'
     endCommit: 'HEAD'
-    outputFile: '$(Build.ArtifactStagingDirectory)/ReleaseNotes.md'
+    outputFileMarkdown: '$(Build.ArtifactStagingDirectory)/release-notes.md'
+    outputFileHtml: '$(Build.ArtifactStagingDirectory)/release-notes.html'
 ```
 
 ### With Custom Template
@@ -33,25 +34,27 @@ The extension analyses Git commits in a specified range, looking for merge commi
   inputs:
     startCommit: 'v1.0.0'
     endCommit: 'v1.1.0'
-    outputFile: 'release-notes.md'
-    templateFile: 'templates/custom-release-notes.hbs'
+    outputFileMarkdown: '$(Build.ArtifactStagingDirectory)/release-notes.md'
+    outputFileHtml: '$(Build.ArtifactStagingDirectory)/release-notes.html'
+    templateFileMarkdown: 'templates/custom-release-notes.hbs'
+    templateFileHtml: 'templates/custom-release-notes.hbs'
 ```
 
 ## Parameters
 | Parameter | Description | Required | Default |
 |-----------|-------------|----------|---------|
 | `startCommit` | Commit reference for the start of the range (exclusive). Can be a commit hash, git tag, or a ref like `HEAD` or `HEAD~xx` | ✅ | - |
 | `endCommit` | Commit reference for the end of the range (inclusive). Can be a commit hash, git tag, or a ref like `HEAD` or `HEAD~xx` | ✅ | `HEAD` |
-| `outputFile` | Path where generated release notes will be saved | ✅ | `$(Build.ArtifactStagingDirectory)/ReleaseNotes.md` |
-| `templateFile` | Path to custom Handlebars template file | ❌ | Built-in template |
+| `outputFileMarkdown` and `outputFileHtml` | Path where generated release notes will be saved | ✅ | `$(Build.ArtifactStagingDirectory)/release-notes.html` and `$(Build.ArtifactStagingDirectory)/release-notes.html` |
+| `templateFileMarkdown` and `templateFileHtml` | Path to custom Handlebars template file | ❌ | Built-in template |
 
 ### Supported commit reference formats for `startCommit` and `endCommit`
 - Commit hash (e.g., `a1b2c3d`)
 - Git tag (e.g., `v1.0.0`)
 - `HEAD` or `HEAD~xx` (where `xx` is the number of commits before HEAD)
 
-## Sample Output
-The [default template](https://github.com/IeuanWalker/AzureDevops-GenerateReleaseNotes/blob/master/CommitRangeReleaseNotesTask/task/defaultTemplate.hbs) outputs the following format - 
+## Output
+The [default markdown template](https://github.com/IeuanWalker/AzureDevops-GenerateReleaseNotes/blob/master/CommitRangeReleaseNotesTask/task/defaultTemplateMarkdown.hbs) outputs the following format - 
 ```markdown
 ## 📊 Summary
 - **3** Pull Requests
@@ -85,6 +88,8 @@ The [default template](https://github.com/IeuanWalker/AzureDevops-GenerateReleas
 | [44](https://dev.azure.com/org/project/_git/pullrequest/44) | Bug fixes and improvements      | Bob Wilson |
 ```
 
+It also generates an interactive html version using this [template.](https://github.com/IeuanWalker/AzureDevops-GenerateReleaseNotes/blob/master/CommitRangeReleaseNotesTask/task/defaultTemplateHtml.hbs)
+
 ## Template Customisation
 The task uses Handlebars templates to format output. You can provide a custom template file or use the built-in default template.
 
@@ -192,21 +197,22 @@ interface WorkItemList {
 {{/if}}
 ```
 
-## Console Usage
+## Local testing
 The task can also be run from the command line for testing.
 
 - Clone the repo
 - Run `npm run build`, in the `CommitRangeReleaseNotesTask` folder
 - Run the following command from the folder `CommitRangeReleaseNotesTask\task\dist`
 ```cmd
-node ./mainConsole.js \
-  --startCommit "v1.0.0" \
-  --endCommit "HEAD" \
-  --outputFile "C:\release-notes.md" \
-  --repoRoot "\path\to\repo" \
-  --systemAccessToken "your-token" \
-  --project "your-project" \
-  --repositoryId "your-repo" \
+node ./mainConsole.js 
+  --startCommit "v1.0.0" 
+  --endCommit "HEAD" 
+  --outputFileMarkdown "C:\release-notes.md" 
+  --outputFileHtml "C:\release-notes.html" 
+  --repoRoot "\path\to\repo" 
+  --systemAccessToken "your-token" 
+  --project "your-project" 
+  --repositoryId "your-repo" 
   --apiUrl "https://dev.azure.com/your-org"
 ```
 > To test locally, the `systemAccessToken` will need to be a [Personal Access Token (PAT)](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows).