bc-release-note-generator

name

bc-release-note-generator

description

Generate structured release notes in markdown format for Business Central projects following the Dynavics DSD template. Creates release notes with all mandatory sections including client name, CCN number, DSD ticket number, issue number, version, date, title, released by, change request details, testing setup, and testing steps. The skill validates that ALL required fields are populated before finalizing. Use when user requests to create, generate, write, or draft a release note, DSD release note, change request document, or deployment note. Trigger phrases include "create release note", "generate release note for DSD", "write release note for [client]", "draft change request document", "create DSD release note", "new release note", or when preparing documentation for a Business Central release or deployment.

Business Central Release Note Generator

Overview

Generates structured release notes in markdown format following the Dynavics DSD release note standard. The skill ensures every release note contains all required sections with populated content. A release note is NOT considered complete until every mandatory field has been filled and validated.

Release Note Structure

The release note structure is defined by the shared field map configuration at:

.github/skills/shared/field-map.json

This JSON file is the single source of truth for all fields used across both the release note generator and the md-to-docx-converter skill. Any field added to the field map is automatically available in both the markdown generation and the Word document conversion.

The current field map defines these sections:

Header Field

#	Field	Key	Required	Format
1	Client Name	ClientName	YES	Text

Extracted from: # Release Note – [value]

Metadata Table Fields

#	Field	Key	Required	Format	Default
2	CCN Nr.	CCNNr	YES	DSD-xxxx	—
3	Issue Nr.	IssueNr	YES	Text	—
4	Version	Version	YES	x.x.x.x	From app.json
5	Date	Date	YES	dd/mm/yyyy	Today
6	Title	Title	YES	Text	—
7	Released By	ReleasedBy	YES	Text	Dynavics

Extracted from the markdown metadata table: | **Label** | Value |

Body Sections

#	Section	Key	Required
8	Change Request Details	ChangeRequestDetails	YES
9	Testing Setup	TestingSetup	YES
10	Testing Steps	TestingSteps	YES

Extracted from ## Heading sections in the markdown.

Adding New Fields

To add a new field to the release note:

1. Add the field to .github/skills/shared/field-map.json:
   • For metadata fields: add an entry to the metadataFields array
   • For body sections: add an entry to the sections array
2. Update the markdown template at .github/skills/bc-release-note-generator/assets/release-note-template.md
3. Add a {{Key}} placeholder in the Word template(s) at .github/skills/md-to-docx-converter/examples/
4. Both skills will automatically pick up the new field — no code changes required

CRITICAL: Completeness Validation

A release note is NOT finished until ALL 10 mandatory fields above are populated.

Before saving the final file, validate every field:

1. Client Name — Must not be empty or contain placeholder text like [Client name]
2. CCN Nr. — Must follow format DSD-xxxx (e.g. DSD-1234)
3. Issue Nr. — Must be a valid number or version string
4. Version — Must be a valid version string (e.g. 1.0, 2.1.0)
5. Date — Must be a valid date in dd/mm/yyyy format
6. Title — Must be a meaningful title, not a placeholder
7. Released By — Must be populated (default: Dynavics)
8. Change Request Details — Must contain at least one paragraph describing the change
9. Testing Setup — Must describe the environment/prerequisites
10. Testing Steps — Must contain numbered steps for verification

If any field is missing or contains placeholder text, prompt the user for the missing information before completing.

Core Workflow

Step 1: Ask the User for 3 Required Fields

Only ask the user for these 3 fields (use ask_questions tool):

#	Field	Key	Notes
1	Client Name	ClientName	Free text — the client receiving the release
2	CCN Nr.	CCNNr	Format: DSD-xxxx — can also be extracted from branch name
3	Issue Nr.	IssueNr	Free text — ticket/issue reference number

If the user already provided any of these in their request message, do not ask again — use the values they gave.

Step 2: Auto-Populate All Other Fields from BC Project Context

All remaining fields are populated automatically. Do NOT ask the user for these.

2a. Read app.json for project metadata

- Version   → app.json → "version" field (e.g. "1.0.0.0")
- Title     → app.json → "name" field (e.g. "BC Dataverse Integration Template")
- Date      → Current date in dd/mm/yyyy format
- Released By → Default: "Dynavics"

2b. Analyze AL workspace objects for Change Request Details

Scan the src/ folder recursively for all .al files. For each file, identify the AL object type, name, and extract Caption properties for functional descriptions.

Procedure:

1. Use file_search with **/*.al to find all AL files in the workspace
2. Read each file (first 30-50 lines) to extract:
   • Object declaration (e.g. table 70000 "BCS Department")
   • Caption property (e.g. Caption = 'Department';) — use this as the functional description
   • For pages: PageType property to describe the page purpose
   • For tables: DataClassification to understand data type
   • For codeunits: XML documentation comments (/// <summary>) if present
3. Also check git log for recent commits on .al files to identify what changed recently
4. Generate a structured Change Request Details section using extracted Captions:

This release delivers the following Business Central extension components:

**Tables:**
- Table 70000 "BCS Department" — Department (Master data for organizational structure)
- Table 70001 "BCS Legal Entity" — Legal Entity (Manages legal entities for compliance)

**Table Extensions:**
- TableExtension "BCS Item" extends Item — Added Dataverse integration fields

**Pages:**
- Page "BCS Departments" (List) — Departments list page for browsing and managing department records
- Page "BCS Department Card" (Card) — Department Card for viewing and editing individual departments

**Page Extensions:**
- PageExtension "BCS Item Card" extends "Item Card" — Added custom Dataverse integration fields group

**Codeunits:**
- Codeunit "BCS CRM Synch Management" — Manages custom CRM/Dataverse synchronization logic
- Codeunit "BCS Dataverse Events" — Event subscribers for Dataverse integration lifecycle

**CDS Integration Tables:**
- Table "BCS CDS bcscountry" (CDS) — Dataverse Countries mapped from Dataverse bcs_country entity
- Table "BCS CDS bcsdepartment" (CDS) — Dataverse Departments mapped from Dataverse bcs_department entity

5. If git history is available, add a "Recent Changes" subsection with the last 5-10 relevant commit messages

2c. Generate Testing Setup from project context

Read app.json to extract runtime, application version, and dependencies. Scan for permission sets. Use Caption properties from AL objects to describe functional prerequisites.

Generate:

**Prerequisites:**
- Business Central [runtime version] or later
- Application version [application version] or later
- Extension "[app name]" version [version] installed
- [If Dataverse tables found] Dataverse connection configured with required entities
- [If permission sets found] Permission set "[name]" assigned to test users

**Environment:**
- Business Central SaaS/On-Premises sandbox environment
- [List any integration dependencies discovered from CDS tables or event subscribers]

**Functional Setup:**
- [Caption from key tables/pages]: Example: "Department master data must be configured before testing"
- [Required data based on captions]: Example: "At least one Legal Entity must exist for compliance testing"

2d. Generate Testing Steps from AL pages and components

For each page, page extension, and key codeunit discovered in the workspace, generate numbered verification steps using extracted Caption and ToolTip information for detailed functional guidance:

Procedure:

1. For each Page object, extract:
   • Caption property (user-friendly page name)
   • PageType (Card, List, Document, etc.)
   • Key fields with ToolTip properties
2. Generate test steps that reference the Caption and include ToolTip context:

### 1. Verify [Caption from Permission Set]
1. Open **Permission Sets** page in Business Central
2. Search for permission set **[Object Name with Caption]**
3. Verify it appears and is Assignable
4. Assign the permission set to your test user

### 2. Test [Caption from Page] ([PageType])
1. Open the **[Caption]** page from the search
2. Verify the page loads without errors and displays the list
3. For key fields (from ToolTips):
   - **[Field Name]**: [ToolTip text] — verify this field is visible and editable
   - **[Field Name]**: [ToolTip text] — test data entry and validation
4. Click **New** to create a record
5. Fill in required fields: [list fields with their ToolTips as guidance]
6. Save and verify the record persists

### 3. Test [Page Extension Caption] extended functionality
1. Open the base page **[Extended page name]**
2. Verify the new group/fields from the extension appear
3. Fields added:
   - **[Field Name]**: [ToolTip] — verify functionality
4. Test field interactions and save

### 4. Test [Codeunit Caption] integration
1. [Based on codeunit XML comments or caption, describe the scenario to trigger]
2. Verify the codeunit logic executes correctly
3. Check results and error handling

This approach ensures testing steps are:

• Functional: Use user-facing Captions instead of technical object names
• Guided: Include ToolTip information so testers understand what each field does
• Comprehensive: Cover all pages, fields, and integration points with context

Step 3: Generate the Release Note

Create the markdown file using the template from assets/release-note-template.md, substituting all gathered and auto-populated values.

File naming convention: Release_Note_[CCNNr]_[ClientName_with_underscores].md

Output location: The docs/releasenotesmd/ folder in the workspace root (create if needed).

Step 4: Validate Completeness

Run through the validation checklist:

✅ Client Name:           [populated — from user]
✅ CCN Nr.:               [DSD-xxxx format — from user]
✅ Issue Nr.:             [populated — from user]
✅ Version:               [valid version — from app.json]
✅ Date:                  [dd/mm/yyyy — auto: today]
✅ Title:                 [meaningful title — from app.json name]
✅ Released By:           [populated — default: Dynavics]
✅ Change Request Details: [auto-generated from AL workspace scan]
✅ Testing Setup:         [auto-generated from app.json + dependencies]
✅ Testing Steps:         [auto-generated from AL pages/components]

If any auto-populated field is empty (e.g. no AL files found): Fill with a reasonable placeholder and inform the user so they can review.

If all checks pass: Confirm completion and display the file path.

Step 5: Report Completion

Only after all validations pass, report:

• File created and path
• Summary: 3 fields from user + 7 fields auto-populated
• List of AL objects discovered and included in the release note
• Confirmation that the release note is complete
• Remind the user they can convert to Word using md-to-docx-converter

Usage Examples

Example 1: User provides all 3 required fields

User: "Create a release note for client Contoso, DSD-4521, issue 789"

→ No questions needed — all 3 user fields provided
→ Auto-populates: Version (app.json), Date (today), Title (app.json name),
   Released By (Dynavics), Change Request Details (AL scan),
   Testing Setup (app.json context), Testing Steps (AL pages/components)
→ Validates and saves

Example 2: User provides partial information

User: "Create a release note for DSD-1234"

→ Asks for: Client Name and Issue Nr. (CCN Nr. already provided)
→ Auto-populates all other 7 fields from BC project context
→ Validates and saves

Example 3: Minimal request

User: "Create a new release note"

→ Asks for: Client Name, CCN Nr., Issue Nr.
→ Scans workspace: reads app.json, discovers AL objects in src/,
   checks git log for recent changes
→ Auto-generates: Change Request Details (lists all tables, pages,
   codeunits, extensions), Testing Setup (BC version requirements,
   dependencies), Testing Steps (verify each page/component)
→ Validates and saves

Template Reference

The release note template is located at:

.github/skills/bc-release-note-generator/assets/release-note-template.md

This template contains the exact markdown structure with placeholder tokens that get replaced with actual values during generation. It references the shared field map via a comment at the top:

<!-- field-map: .github/skills/shared/field-map.json -->

The field map configuration is at:

.github/skills/shared/field-map.json

Both the template and the field map must stay in sync. When adding new fields, update both files.

Auto-Population Rules

The field map at .github/skills/shared/field-map.json defines which fields are asked from the user ("askUser": true) and which are auto-populated ("askUser": false).

User-Provided Fields (3 fields — always ask if not provided)

Field	Key	How to Get
Client Name	ClientName	Ask user
CCN Nr.	CCNNr	Ask user (or extract from branch name)
Issue Nr.	IssueNr	Ask user

Auto-Populated Fields (7 fields — NEVER ask the user)

Field	Key	Source
Version	Version	Read app.json → "version"
Date	Date	Current date in dd/mm/yyyy format
Title	Title	Read app.json → "name"
Released By	ReleasedBy	Default: "Dynavics"
Change Request Details	ChangeRequestDetails	Scan src/**/*.al files, group by object type, optionally include recent git commits
Testing Setup	TestingSetup	Generate from app.json runtime/application version + discovered dependencies
Testing Steps	TestingSteps	Generate verification steps for each discovered page, page extension, table, and codeunit

AL Workspace Scanning Procedure

To auto-populate the 3 body sections, scan the workspace as follows:

1. Find all AL files: file_search with pattern src/**/*.al

2. Extract metadata from each AL file: Read the first 30-50 lines to extract:

   • Object declaration: Object type and name (e.g. table 70000 "BCS Department", pageextension 50100 "BCS Item Card" extends "Item Card")
   • Caption property: Caption = 'Department'; — User-friendly name for functional documentation
   • PageType property (for pages): PageType = List; or PageType = Card; — Describes the page purpose
   • ToolTip properties (for fields): ToolTip = 'Specifies the department name.'; — Field-level help text for testing guidance
   • XML documentation comments (for codeunits): /// <summary> blocks — Functional description of the codeunit logic
   • TableType property (for tables): TableType = CDS; — Identifies Dataverse integration tables

3. Categorize objects: Group into Tables, Table Extensions, Pages, Page Extensions, Codeunits, Enums, Reports, Queries, XMLPorts, Permission Sets

4. Build functional descriptions:

   • For each object, use the Caption as the primary description
   • For pages, add the PageType to clarify purpose (e.g. "Departments (List)")
   • For tables with TableType = CDS, add "(CDS)" to indicate Dataverse integration
   • For fields, collect ToolTip text to use in testing steps

5. Check git history (optional): Run git log --oneline -10 -- "*.al" to get recent AL-related commits

6. Generate sections using extracted metadata:

   • Change Request Details: List all objects with their Caption-based descriptions
   • Testing Setup: Use Caption and PageType to describe functional prerequisites
   • Testing Steps: Generate detailed steps referencing Caption for page names and ToolTip for field guidance

Example of metadata extraction:

// From BCSCDSProducts.Page.al
page 70002 "BCS CDS Products"
{
    Caption = 'Dataverse Products';                    ← Extract this for functional name
    PageType = List;                                   ← Extract this for page purpose
    
    field(name; Rec.name)
    {
        ToolTip = 'Specifies the name of the product.'; ← Extract this for testing guidance
    }
}

Resulting documentation:

• Change Request Details: "Page 70002 'BCS CDS Products' (List) — Dataverse Products list integration"
• Testing Steps: "Verify the name field — Specifies the name of the product"

All other fields must NOT be asked from the user — they are derived from the project context.

Integration with Other Skills

Release note + Word document workflow:

1. Use bc-release-note-generator to create the markdown release note
2. Use md-to-docx-converter to convert to a formatted Word document with corporate template
3. Result: Professional release note in both .md and .docx formats

Validation Error Messages

When a field fails validation, provide clear guidance:

• Empty field: "❌ [Field Name] is required. Please provide a value."
• Invalid format: "❌ [Field Name] format is invalid. Expected: [format]. Got: [value]"
• Placeholder text: "❌ [Field Name] still contains placeholder text. Please replace with actual content."