Harpinder's prompt and the result

Author: bc-devrev

changelog_prompt.md

@@ -1,42 +1,5 @@
-# Prompt
+Please provide an API changelog from the following OASDiff of openapi spec changes. The output should be in markdown format grouping endpoints by use case/ object type. For cases where some schema is modified, please also tell what endpoints it affects.
 
-You are a technical writer creating release notes for an API.
-
-## Target Audience
-The audience for the release notes consists of experienced developers who integrate the API into their applications. They rely on detailed documentation, advance notice of upcoming features, and clear information about potential breaking changes.
-
-## Source Content Structure
-The changelog lists each endpoint that has changed and presents changes in a tree structure:
-- The most specific, actionable changes are found in the leaf nodes (deepest level) of each tree
-- Higher levels provide context but the actual modifications are at the leaves
-- When multiple endpoints show identical tree structures, they are receiving the same modification and should be grouped together
-- Every endpoint listed must be accounted for in the summary
-
-## Analysis Guidelines
-When analyzing the changelog:
-1. Look carefully at the leaf nodes in each change tree
-2. Check if the change pattern matches other endpoints already documented
-3. Group similar changes together even if they appear in different parts of the changelog
-4. Never mark changes as "unspecified" - the specific modification is always in the leaf nodes
-5. Don't ask for clarification - instead, look more carefully at the patterns and leaf nodes
-
-## Output Requirements
-1. Group changes by type (e.g., "New endpoints", "API Modifications") and then by shared modifications (e.g., "Sync metadata support", "Follow-up relationship support") rather than by endpoint
-2. Ensure every endpoint from the changelog is included in the summary
-3. Follow each tree to its leaves and document the specific change
-
-## Style Rules
-1. Use sentence-case capitalization for headings and descriptions
-2. Avoid adjectives. Be plain and clear. This is technical documentation, not marketing material
-3. Be precise with endpoint and class names
-4. Keep the language concise and technical
-5. Ignore grammar/style changes in the changelog
-
-## Markdown Syntax
-1. Use the header # Today's date for the title
-2. Use markdown headers (##, ###, ####) to structure the subheadings
-3. Link endpoints using [`endpoint.name`](/endpoint/name)
-4. Surround endpoints and fields in backticks
-5. Speak in second-person voice ("you") directly to developers
-
-The generated changelog is attached to this request.
+<oasdiff>
+{{oasdiff}}
+</oasdiff>

fern/apis/beta/changelog/2024-12-02.md

@@ -1,71 +1,55 @@
-# December 2, 2024
+# 2024-12-02
 
 ## New Endpoints
-- [`/dev-users.activate`](/beta/api-reference/dev-users/activate) - Activate a developer user
-- [`/dev-users.deactivate`](/beta/api-reference/dev-users/deactivate) - Deactivate a developer user
-
-## API Modifications
-
-### Article Scope Changes
-The `scope` parameter description was updated in:
-- [`/articles.count`](/beta/api-reference/articles/count) (GET and POST)
-- [`/articles.list`](/beta/api-reference/articles/list) (GET and POST)
-
-### Parts Schema Updates
-Added `custom_schema_spec` field to request bodies in:
-- [`/parts.create`](/beta/api-reference/parts/create)
-- [`/parts.update`](/beta/api-reference/parts/update)
-
-### Auth Connection Deprecations
-Marked Azure AD and Google Apps connection types as deprecated in:
-- [`/dev-orgs.auth-connections.create`](/beta/api-reference/dev-orgs/auth-connections/create)
-- [`/dev-orgs.auth-connections.get`](/beta/api-reference/dev-orgs/auth-connections/get)
-- [`/dev-orgs.auth-connections.list`](/beta/api-reference/dev-orgs/auth-connections/list)
-- [`/dev-orgs.auth-connections.update`](/beta/api-reference/dev-orgs/auth-connections/update)
-
-### Incident Support
-Added incident type support across multiple endpoints:
-
-#### Timeline and Conversation Endpoints
-Added `incident` to supported object types in:
-- [`/conversations.create`](/beta/api-reference/conversations/create)
-- [`/conversations.export`](/beta/api-reference/conversations/export)
-- [`/conversations.get`](/beta/api-reference/conversations/get)
-- [`/conversations.list`](/beta/api-reference/conversations/list)
-- [`/conversations.update`](/beta/api-reference/conversations/update)
-- [`/timeline-entries.create`](/beta/api-reference/timeline-entries/create)
-- [`/timeline-entries.get`](/beta/api-reference/timeline-entries/get)
-- [`/timeline-entries.list`](/beta/api-reference/timeline-entries/list)
-- [`/timeline-entries.update`](/beta/api-reference/timeline-entries/update)
-
-#### Search Endpoints
-Added incident support to search results in:
-- [`/search.core`](/beta/api-reference/search/core)
-- [`/search.hybrid`](/beta/api-reference/search/hybrid)
-
-#### Links and Schema Endpoints
-Added incident type to object references in:
-- [`/links.create`](/beta/api-reference/links/create)
-- [`/links.get`](/beta/api-reference/links/get)
-- [`/links.list`](/beta/api-reference/links/list)
-- [`/schemas.stock.get`](/beta/api-reference/schemas/stock/get)
-- [`/schemas.stock.list`](/beta/api-reference/schemas/stock/list)
-
-#### Webhook Events
-Added new incident event types:
-- `incident_created`
-- `incident_deleted`
-- `incident_updated`
-
-These events are available in:
-- [`/webhooks.create`](/beta/api-reference/webhooks/create)
-- [`/webhooks.get`](/beta/api-reference/webhooks/get)
-- [`/webhooks.list`](/beta/api-reference/webhooks/list)
-- [`/webhooks.update`](/beta/api-reference/webhooks/update)
-
-### Work Updates
-Added sync resolution fields to `staged_info` in:
-- [`/works.update`](/beta/api-reference/works/update)
-  - Added `sync_in_unresolved_fields`
-  - Added `sync_out_unresolved_fields`
-  - Removed `unresolved_fields`
+### Dev Users
+- `POST /dev-users.activate` - New endpoint
+- `POST /dev-users.deactivate` - New endpoint
+
+## Modified Endpoints
+### Articles
+- Modified description for `scope` parameter in:
+  - `GET /articles.count`
+  - `POST /articles.count` 
+  - `GET /articles.list`
+  - `POST /articles.list`
+  - Description changed to: "Filter for the scope of the articles."
+
+### Parts
+- Added `custom_schema_spec` property to request body in:
+  - `POST /parts.create`
+  - `POST /parts.update`
+
+### Works
+- Modified `staged_info` in `POST /works.update`:
+  - Removed required property: `unresolved_fields`
+  - Added new properties:
+    - `sync_in_unresolved_fields`
+    - `sync_out_unresolved_fields`
+
+### Auth Connections
+- Deprecated Azure AD and Google Apps auth connection options in:
+  - `POST /dev-orgs.auth-connections.create`
+  - `GET /dev-orgs.auth-connections.get`
+  - `POST /dev-orgs.auth-connections.get`
+  - `GET /dev-orgs.auth-connections.list`
+  - `POST /dev-orgs.auth-connections.list`
+  - `POST /dev-orgs.auth-connections.update`
+
+### Webhooks
+- Added new event types (`incident_created`, `incident_deleted`, `incident_updated`) to:
+  - `POST /webhooks.create`
+  - `GET /webhooks.get`
+  - `POST /webhooks.get`
+  - `GET /webhooks.list`
+  - `POST /webhooks.list`
+  - `POST /webhooks.update`
+
+## Schema Changes
+Added support for incident type across multiple schemas affecting:
+- Conversations endpoints
+- Links endpoints
+- Timeline entries endpoints
+- Search endpoints
+- Schemas stock endpoints
+
+The incident type was added to object types, event types, and reference types in these endpoints' response schemas.