New members include their descriptions in the changelog, if present

examples/vitepress/docs/changelog.md

@@ -75,4 +75,4 @@ These custom fields have been added or removed.
 
 ### Contact
 
-- New Field: PhotoUrl__c
+- New Field: PhotoUrl__c. URL of the contact's photo

examples/vitepress/docs/custom-objects/Contact.md

@@ -10,6 +10,8 @@ title: Contact
 ## Fields
 ### PhotoUrl
 
+URL of the contact's photo
+
 **API Name**
 
 `apexdocs__PhotoUrl__c`

examples/vitepress/force-app/main/default/objects/Contact/fields/PhotoUrl__c.field-meta.xml

@@ -6,4 +6,5 @@
     <required>false</required>
     <trackFeedHistory>false</trackFeedHistory>
     <type>Url</type>
+    <description>URL of the contact's photo</description>
 </CustomField>

src/core/changelog/__test__/processing-changelog.spec.ts

@@ -14,19 +14,25 @@ function apexTypeFromRawString(raw: string): Type {
 
 class CustomFieldMetadataBuilder {
   name: string = 'MyField';
+  description: string | null = null;
 
   withName(name: string): CustomFieldMetadataBuilder {
     this.name = name;
     return this;
   }
 
+  withDescription(testDescription: string) {
+    this.description = testDescription;
+    return this;
+  }
+
   build(): CustomFieldMetadata {
     return {
       type: 'Text',
       type_name: 'customfield',
       label: 'MyField',
       name: this.name,
-      description: null,
+      description: this.description,
       parentName: 'MyObject',
     };
   }
@@ -178,6 +184,7 @@ describe('when generating a changelog', () => {
             {
               __typename: 'NewField',
               name: newField.name,
+              description: null,
             },
           ],
         },
@@ -605,6 +612,33 @@ describe('when generating a changelog', () => {
             {
               __typename: 'NewField',
               name: newField.name,
+              description: null,
+            },
+          ],
+        },
+      ]);
+    });
+
+    it('includes the description of new fields', () => {
+      const oldField = new CustomFieldMetadataBuilder().build();
+      const newField = new CustomFieldMetadataBuilder()
+        .withName('NewField')
+        .withDescription('Test description')
+        .build();
+
+      const oldManifest = { types: [oldField] };
+      const newManifest = { types: [oldField, newField] };
+
+      const changeLog = processChangelog(oldManifest, newManifest);
+
+      expect(changeLog.customObjectModifications).toEqual([
+        {
+          typeName: newField.parentName,
+          modifications: [
+            {
+              __typename: 'NewField',
+              name: newField.name,
+              description: 'Test description',
             },
           ],
         },

src/core/changelog/process-changelog.ts

@@ -23,6 +23,7 @@ type ModificationTypes =
 export type MemberModificationType = {
   __typename: ModificationTypes;
   name: string;
+  description?: string | null | undefined;
 };
 
 export type NewOrModifiedMember = {
@@ -142,7 +143,10 @@ function getNewOrModifiedExtensionFields(
       ...previous.filter((parent) => parent.typeName !== parentName),
       {
         typeName: parentName,
-        modifications: [...additionsToParent, { __typename: 'NewField', name: currentField.name }],
+        modifications: [
+          ...additionsToParent,
+          { __typename: 'NewField', name: currentField.name, description: currentField.description },
+        ],
       },
     ] as NewOrModifiedMember[];
   }, [] as NewOrModifiedMember[]);
@@ -284,6 +288,7 @@ function getCustomObjectsInBothVersions(
 
 type NameAware = {
   name: string;
+  description?: string | null;
 };
 
 type AreEqualFn<T> = (oldValue: T, newValue: T) => boolean;
@@ -301,8 +306,7 @@ function getNewValues<Searchable extends NameAware, T extends Record<K, Searchab
 ): MemberModificationType[] {
   return newPlaceToSearch[keyToSearch]
     .filter((newValue) => !oldPlaceToSearch[keyToSearch].some((oldValue) => areEqualFn(oldValue, newValue)))
-    .map((value) => value.name)
-    .map((name) => ({ __typename: typeName, name }));
+    .map(({ name, description }) => ({ __typename: typeName, name, description }));
 }
 
 function getRemovedValues<Named extends NameAware, T extends Record<K, Named[]>, K extends keyof T>(

src/core/changelog/renderable-changelog.ts

@@ -151,25 +151,32 @@ function toRenderableModification(newOrModifiedMember: NewOrModifiedMember): New
 }
 
 function toRenderableModificationDescription(memberModificationType: MemberModificationType): string {
+  function withDescription(memberModificationType: MemberModificationType): string {
+    if (memberModificationType.description) {
+      return `${memberModificationType.name}. ${memberModificationType.description}`;
+    }
+    return memberModificationType.name;
+  }
+
   switch (memberModificationType.__typename) {
     case 'NewEnumValue':
-      return `New Enum Value: ${memberModificationType.name}`;
+      return `New Enum Value: ${withDescription(memberModificationType)}`;
     case 'RemovedEnumValue':
       return `Removed Enum Value: ${memberModificationType.name}`;
     case 'NewMethod':
-      return `New Method: ${memberModificationType.name}`;
+      return `New Method: ${withDescription(memberModificationType)}`;
     case 'RemovedMethod':
       return `Removed Method: ${memberModificationType.name}`;
     case 'NewProperty':
-      return `New Property: ${memberModificationType.name}`;
+      return `New Property: ${withDescription(memberModificationType)}`;
     case 'RemovedProperty':
       return `Removed Property: ${memberModificationType.name}`;
     case 'NewField':
-      return `New Field: ${memberModificationType.name}`;
+      return `New Field: ${withDescription(memberModificationType)}`;
     case 'RemovedField':
       return `Removed Field: ${memberModificationType.name}`;
     case 'NewType':
-      return `New Type: ${memberModificationType.name}`;
+      return `New Type: ${withDescription(memberModificationType)}`;
     case 'RemovedType':
       return `Removed Type: ${memberModificationType.name}`;
   }