Skip to content

Commit 94eca0b

Browse files
bc-devrevbc-devrev
authored
launch API changelogs (#136)
* from PR #122 * run changelog script and commit final output * generated by Claude * changelog nav reference * fixed link * prompt refinement * generated by Claude (Dec. 2 changes) * removed extraneous statements * address bdbyrne's comments * cosmetic changes
1 parent fe2c0fb commit 94eca0b

File tree

8 files changed

+345
-4
lines changed

8 files changed

+345
-4
lines changed

‎.github/workflows/oasdiff.yml renamed to ‎.github/workflows/changelog.yml

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,23 +24,31 @@ jobs:
2424
path: base
2525
- name: Create dir
2626
run: |
27-
mkdir -p changelog/beta changelog/public
27+
mkdir -p temp/beta temp/public
2828
- name: Running public OpenAPI Spec diff action
2929
uses: oasdiff/oasdiff-action/diff@main
3030
with:
3131
base: 'base/fern/apis/public/openapi-public.yaml'
3232
revision: 'head/fern/apis/public/openapi-public.yaml'
3333
format: text
34-
output-to-file: 'changelog/public/${{ steps.date.outputs.date }}_oasdiff.md'
34+
output-to-file: 'temp/public/${{ steps.date.outputs.date }}_oasdiff.md'
3535
- name: Running beta OpenAPI Spec diff action
3636
uses: oasdiff/oasdiff-action/diff@main
3737
with:
3838
base: 'base/fern/apis/beta/openapi-beta.yaml'
3939
revision: 'head/fern/apis/beta/openapi-beta.yaml'
4040
format: text
4141
output-to-file: 'changelog/beta/${{ steps.date.outputs.date }}_oasdiff.md'
42+
- name: Prompt
43+
run: |
44+
python changelog.py --date ${{ steps.date.outputs.date }}
45+
git config user.name github-actions
46+
git config user.email github-actions@github.com
47+
git add fern/apis/*/changelog
48+
git commit -m "generated by Claude"
49+
git push
4250
- name: Archive changelogs
4351
uses: actions/upload-artifact@v4
4452
with:
45-
name: changelog
46-
path: changelog/**
53+
name: changelog-${{ steps.date.outputs.date }}
54+
path: temp/**

‎changelog.py

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
import yaml
2+
import argparse
3+
import requests
4+
import os
5+
import datetime
6+
import re
7+
8+
9+
def main(vrn, d):
10+
11+
print(f"Generating prompt for `{vrn}` API on {d}.")
12+
13+
p = gen_prompt(f"temp/{vrn}/{d}_oasdiff.md", get_links(vrn), vrn)
14+
15+
pr_file = f"temp/{vrn}/{d}_prompt.md"
16+
with open(pr_file, 'w', encoding="utf-8") as outfile:
17+
outfile.write(p)
18+
print(f"Wrote prompt to {pr_file}.")
19+
20+
l = gen_log(p)
21+
22+
log_file = f"./fern/apis/{vrn}/changelog/{d}.md"
23+
with open(log_file, 'w', encoding="utf-8") as outfile:
24+
outfile.write(l)
25+
print(f"Wrote log to {log_file}.")
26+
27+
28+
def gen_log(prompt):
29+
30+
log = None
31+
auth = os.environ.get('LLM_JWT')
32+
headers = {"Content-Type": "application/json", "Authorization": f"Bearer {auth}"}
33+
payload = {
34+
"model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
35+
"messages": [
36+
{
37+
"role": "user",
38+
"content": prompt
39+
}
40+
]
41+
}
42+
43+
try:
44+
r = requests.post('https://openwebui.dev.devrev-eng.ai/api/chat/completions', json=payload,
45+
headers=headers)
46+
log = r.json()['choices'][0]['message']['content']
47+
log = re.sub(r"^Here's.*\n?", '', log, flags=re.MULTILINE)
48+
log = re.sub(r"^Let me know.*\n?", '', log, flags=re.MULTILINE)
49+
except Exception as e:
50+
print(
51+
f"Failed to generate changelog. Error: {type(e)} {e} {r}")
52+
return log
53+
54+
55+
def gen_prompt(oasdiff, links, version):
56+
with open(oasdiff, 'r') as infile:
57+
oasdiff = infile.read()
58+
59+
prompt = f"""
60+
Please provide an API changelog for the {version} API 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. Wherever an endpoint, property, or enum value is mentioned, surround it with backticks (`). Wherever an API is mentioned, include a hyperlink to the corresponding path from `<api_links>` section.
61+
62+
<oasdiff>
63+
{oasdiff}
64+
</oasdiff>
65+
66+
<api_links>
67+
{links}
68+
</api_links>
69+
"""
70+
71+
return prompt
72+
73+
def get_links(version):
74+
75+
src = f"./fern/apis/{version}/openapi-{version}.yaml"
76+
77+
with open(src, 'r') as s:
78+
spec = yaml.safe_load(s)
79+
apis = {}
80+
for endp, defn in spec['paths'].items():
81+
for val in defn.values():
82+
tag = val.get('tags')[0]
83+
opId = val.get('operationId')
84+
api = {'opId' : opId, 'method': endp.split('.')[-1]}
85+
api['target'] = f"/{version}/api-reference/{tag}/{opId.replace(f'{tag}-', '')}"
86+
if tag not in apis:
87+
apis[tag] = {endp: api}
88+
else:
89+
apis[tag][endp] = api
90+
91+
md = f"# {version}\n\n"
92+
for tag, api in sorted(apis.items()):
93+
md += f"\n## {tag}\n\n"
94+
for endp, val in api.items():
95+
link_text = f"**{tag} > {val['method']}**: `{val['opId']}`"
96+
md += f"- [{endp}]({val['target']}) {link_text}\n"
97+
return md
98+
99+
if __name__ == "__main__":
100+
parser = argparse.ArgumentParser(description="Generate release notes")
101+
parser.add_argument('--date', default=datetime.date.today())
102+
parser.add_argument('--beta', default=True,
103+
action=argparse.BooleanOptionalAction)
104+
parser.add_argument('--public', default=True,
105+
action=argparse.BooleanOptionalAction)
106+
args = parser.parse_args()
107+
if args.beta:
108+
main('beta', args.date)
109+
if args.public:
110+
main('public', args.date)

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

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
2+
# API Changelog
3+
4+
## New Endpoints
5+
6+
### Airdrop
7+
- Added `GET` and `POST` [`/airdrop.sync-units.get`](/beta/api-reference/airdrop/sync-units-get-post) to get sync units
8+
- Added `GET` and `POST` [`/airdrop.sync-units.history`](/beta/api-reference/airdrop/sync-units-history-post) to get sync unit history
9+
10+
### Meetings
11+
- Added `GET` and `POST` [`/meetings.count`](/beta/api-reference/meetings/count-post) to count meetings
12+
- Added `POST` [`/meetings.create`](/beta/api-reference/meetings/create) to create meetings
13+
- Added `POST` [`/meetings.delete`](/beta/api-reference/meetings/delete) to delete meetings
14+
- Added `GET` and `POST` [`/meetings.get`](/beta/api-reference/meetings/get-post) to get meeting details
15+
- Added `GET` and `POST` [`/meetings.list`](/beta/api-reference/meetings/list-post) to list meetings
16+
- Added `POST` [`/meetings.update`](/beta/api-reference/meetings/update) to update meetings
17+
18+
### Schedule Related
19+
- Added `GET` and `POST` [`/org-schedules.evaluate`](/beta/api-reference/schedules/org-evaluate-post) to evaluate schedules
20+
21+
### Recommendations
22+
- Added `POST` [`/recommendations.get-reply`](/beta/api-reference/recommendations/get-reply) to get recommendations reply
23+
24+
### Survey
25+
- Added `POST` [`/surveys.update`](/beta/api-reference/surveys/update) to update surveys
26+
27+
## Modified Endpoints
28+
29+
### Account Management
30+
The following endpoints have been updated to support a new `websites` property:
31+
32+
- [`/accounts.create`](/beta/api-reference/accounts/create)
33+
- [`/accounts.export`](/beta/api-reference/accounts/export-post)
34+
- [`/accounts.get`](/beta/api-reference/accounts/get-post)
35+
- [`/accounts.list`](/beta/api-reference/accounts/list-post)
36+
- [`/accounts.update`](/beta/api-reference/accounts/update)
37+
38+
### Authentication
39+
New `okta` enum value added for `type` property in:
40+
41+
- [`/dev-orgs.auth-connections.create`](/beta/api-reference/auth-connection/dev-org-auth-connections-create)
42+
- [`/dev-orgs.auth-connections.get`](/beta/api-reference/auth-connection/dev-org-auth-connections-get-post)
43+
- [`/dev-orgs.auth-connections.list`](/beta/api-reference/auth-connection/dev-org-auth-connections-list-post)
44+
- [`/dev-orgs.auth-connections.update`](/beta/api-reference/auth-connection/dev-org-auth-connections-update)
45+
46+
### Schema Changes
47+
UI schema properties updated with new fields across multiple endpoints:
48+
- Added `is_currency_field`
49+
- Added `order`
50+
- Added `unit`
51+
52+
This affects endpoints that handle schemas including:
53+
- [`/schemas.custom.get`](/beta/api-reference/customization/custom-schema-fragments-get-post)
54+
- [`/schemas.custom.list`](/beta/api-reference/customization/custom-schema-fragments-list-post)
55+
- [`/schemas.custom.set`](/beta/api-reference/customization/custom-schema-fragments-set)
56+
57+
### Webhooks
58+
New event types added to webhook related endpoints:
59+
- `sync_history_created`
60+
- `sync_history_deleted`
61+
- `sync_history_updated`
62+
- `sync_unit_updated`
63+
64+
Affects:
65+
- [`/webhooks.create`](/beta/api-reference/webhooks/create)
66+
- [`/webhooks.get`](/beta/api-reference/webhooks/get-post)
67+
- [`/webhooks.list`](/beta/api-reference/webhooks/list-post)
68+
- [`/webhooks.update`](/beta/api-reference/webhooks/update)

‎fern/apis/beta/changelog/2025-01-08.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
2+
### New Features
3+
4+
#### Commands
5+
New endpoints for managing commands:
6+
- [`/commands.create`](/beta/api-reference/command/commands-create)
7+
- [`/commands.get`](/beta/api-reference/command/commands-get-post)
8+
- [`/commands.list`](/beta/api-reference/command/commands-list-post)
9+
- [`/commands.update`](/beta/api-reference/command/commands-update)
10+
11+
#### Preferences
12+
New endpoint for updating preferences:
13+
- [`/preferences.update`](/beta/api-reference/preferences/update)
14+
15+
#### Reactions
16+
New endpoints for managing reactions:
17+
- [`/reactions.list`](/beta/api-reference/timeline-entries/reactions-list-post)
18+
- [`/reactions.update`](/beta/api-reference/timeline-entries/reactions-update)
19+
20+
#### Recommendations
21+
New endpoint for chat completions:
22+
- [`/recommendations.chat.completions`](/beta/api-reference/recommendations/chat-completions)
23+
24+
#### Rev User Associations
25+
New endpoints for managing rev user associations:
26+
- [`/rev-users.associations.list`](/beta/api-reference/rev-users/associations-list-post)
27+
28+
### Modified Features
29+
30+
#### Articles
31+
Added `value` property to `scope` in article responses for:
32+
- [`/articles.create`](/beta/api-reference/articles/create-article)
33+
- [`/articles.get`](/beta/api-reference/articles/get-article-post)
34+
- [`/articles.list`](/beta/api-reference/articles/list-articles-post)
35+
- [`/articles.update`](/beta/api-reference/articles/update-article)
36+
37+
#### Conversations
38+
Added `sla_summary` property to conversation responses for:
39+
- [`/conversations.create`](/beta/api-reference/conversations/create)
40+
- [`/conversations.export`](/beta/api-reference/conversations/export-post)
41+
- [`/conversations.get`](/beta/api-reference/conversations/get-post)
42+
- [`/conversations.list`](/beta/api-reference/conversations/list-post)
43+
- [`/conversations.update`](/beta/api-reference/conversations/update)
44+
45+
#### Meetings
46+
Added `scheduled_date` and `ended_date` properties to:
47+
- [`/meetings.count`](/beta/api-reference/meetings/count-post)
48+
- [`/meetings.list`](/beta/api-reference/meetings/list-post)
49+
50+
#### Rev Users
51+
Added `associations` parameter to:
52+
- [`/rev-users.list`](/beta/api-reference/rev-users/list-post)
53+
- [`/rev-users.scan`](/beta/api-reference/rev-users/scan-post)
54+
55+
#### Works
56+
For `opportunity` type works, added `annual_contract_value` and `value` properties in:
57+
- [`/works.create`](/beta/api-reference/works/create)
58+
- [`/works.update`](/beta/api-reference/works/update)
59+
60+
### Schema Changes
61+
62+
Several object schemas have been modified with updated example values and property changes:
63+
64+
1. Account schema changes affect account-related endpoints:
65+
- Removed requirement for property `external_refs`
66+
- Updated examples for `custom_schema_fragments` and `stock_schema_fragment`
67+
68+
2. DevUser schema changes affect dev user endpoints:
69+
- Added `value` property to `employment_status` in job history
70+
- Updated examples for schema fragment properties
71+
72+
3. Incident schema changes affect incident endpoints:
73+
- Added `value` property to `impact.count`, `reported_by`, `severity`, and `source`
74+
- Updated schema fragment examples
75+
76+
4. Survey Response schema changes affect survey endpoints:
77+
- Added `value` property to `dispatched_channels`, `response_channel`, and `stage`
78+
79+
These schema changes maintain backwards compatibility while providing enhanced functionality.

‎fern/apis/public/changelog/2024-12-02.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
2+
# API Changelog
3+
4+
## Modified Endpoints
5+
6+
### Accounts
7+
The following account-related endpoints now support a new `websites` property in requests/responses:
8+
9+
- [`/accounts.create`](/public/api-reference/accounts/create)
10+
- [`/accounts.export`](/public/api-reference/accounts/export-post)
11+
- [`/accounts.get`](/public/api-reference/accounts/get-post)
12+
- [`/accounts.list`](/public/api-reference/accounts/list-post)
13+
- [`/accounts.update`](/public/api-reference/accounts/update)
14+
15+
### Auth Connections
16+
Several changes to auth connection endpoints:
17+
18+
- Added support for `okta` as a new auth connection type
19+
- Relaxed requirements for existing auth connection types (Azure AD, Google Apps, OIDC, SAML)
20+
- Updated required fields for SAML connections
21+
22+
Affected endpoints:
23+
- [`/dev-orgs.auth-connections.create`](/public/api-reference/auth-connection/dev-org-auth-connections-create)
24+
- [`/dev-orgs.auth-connections.get`](/public/api-reference/auth-connection/dev-org-auth-connections-get-post)
25+
- [`/dev-orgs.auth-connections.list`](/public/api-reference/auth-connection/dev-org-auth-connections-list-post)
26+
- [`/dev-orgs.auth-connections.update`](/public/api-reference/auth-connection/dev-org-auth-connections-update)
27+
28+
### SLAs
29+
Added `websites` property to account selector in:
30+
- [`/slas.create`](/public/api-reference/slas/create)
31+
- [`/slas.update`](/public/api-reference/slas/update)
32+
33+
### Webhooks
34+
Added new event types: `sync_history_created`, `sync_history_deleted`, `sync_history_updated`, `sync_unit_updated` to:
35+
- [`/webhooks.create`](/public/api-reference/webhooks/create)
36+
- [`/webhooks.get`](/public/api-reference/webhooks/get-post)
37+
- [`/webhooks.list`](/public/api-reference/webhooks/list-post)
38+
- [`/webhooks.update`](/public/api-reference/webhooks/update)

‎fern/apis/public/changelog/2025-01-08.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
2+
### Accounts
3+
Modified endpoints that handle account objects ([accounts API reference](/public/api-reference/accounts)):
4+
- Made `external_refs` an optional property in account objects for endpoints:
5+
- [`/accounts.create`](/public/api-reference/accounts/create)
6+
- [`/accounts.export`](/public/api-reference/accounts/export-post)
7+
- [`/accounts.get`](/public/api-reference/accounts/get-post)
8+
- [`/accounts.list`](/public/api-reference/accounts/list-post)
9+
- [`/accounts.update`](/public/api-reference/accounts/update)
10+
11+
### Dev Users
12+
Updated endpoints that handle dev user objects ([dev-users API reference](/public/api-reference/dev-users)):
13+
- Added `value` property to `employment_status` in job history for endpoints:
14+
- [`/dev-users.get`](/public/api-reference/dev-users/get-post)
15+
- [`/dev-users.list`](/public/api-reference/dev-users/list-post)
16+
- [`/dev-users.self`](/public/api-reference/dev-users/self-post)
17+
18+
### Webhooks
19+
For [`/webhooks.event`](/public/api-reference/webhooks/event):
20+
- Added new property `ai_agent_response`
21+
- Added `sla_summary` property to conversations and works
22+
- Added `value` property to various enum fields in incidents, survey responses, and tickets
23+
24+
### Works
25+
Modified endpoints that handle work objects ([works API reference](/public/api-reference/works)):
26+
- Added `sla_summary` property to issues and tickets
27+
- Added `value` property to ticket sentiment field
28+
29+
These changes affect the following endpoints:
30+
- [`/works.create`](/public/api-reference/works/create)
31+
- [`/works.export`](/public/api-reference/works/export-post)
32+
- [`/works.get`](/public/api-reference/works/get-post)
33+
- [`/works.list`](/public/api-reference/works/list-post)
34+
- [`/works.update`](/public/api-reference/works/update)

‎fern/versions/beta.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ navigation:
99
- docs
1010
snippets:
1111
typescript: "@devrev/api"
12+
- changelog: ../apis/beta/changelog
13+
title: Changelog
1214
- section: Guides
1315
contents:
1416
- page: Object customization

‎fern/versions/public.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@ navigation:
5656
- slas:
5757
- page: Service level agreement
5858
path: ../docs/pages/entities/sla.mdx
59+
- changelog: ../apis/public/changelog
60+
title: Changelog
5961
- section: Guides
6062
slug: guides
6163
contents:

0 commit comments

Comments
 (0)