feat: add RUNBOOK playbooks and release-please CHANGELOG automation - #840
feat: add RUNBOOK playbooks and release-please CHANGELOG automation#840legalienn wants to merge 1 commit into
Conversation
Add 4 new operational playbooks to RUNBOOK.md for on-call resolution: indexer falls behind, webhook dead-letter spike, SQLite WAL size growth, and contract invocation timeout. Set up CHANGELOG automation with commitlint enforcement (conventional commits), husky commit-msg hook, release-please multi-package config, and updated PR template with commit type selector. Closes ritik4ever#792 Closes ritik4ever#805
|
@Netty-kun is attempting to deploy a commit to the ritik4ever's projects Team on Vercel. A member of the Team first needs to authorize it. |
|
@legalienn Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
📝 WalkthroughWalkthroughThe PR adds Conventional Commit enforcement, expands the pull request template, configures Release Please for workspace releases, adds the ChangesRelease and Commit Workflow
Operational Runbook Expansion
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@release-please-config.json`:
- Around line 26-29: Add the missing contracts version source by creating
contracts/version.txt with the current package version, or update the contracts
entry in release-please-config.json to reference an existing version file.
Ensure the release-type simple configuration has a valid version source.
- Around line 50-51: Update the bootstrap-sha setting in the release
configuration to the appropriate 40-character commit SHA instead of HEAD.
Preserve the setting until the first Release Please-generated release PR is
merged, then remove bootstrap-sha.
In `@RUNBOOK.md`:
- Around line 210-214: Update the SQLite command in the “Inspect dead-letter
payloads” runbook step to use the CLI’s JSON output mode before piping results
to jq, while preserving the existing query and row limit.
- Around line 199-202: Update the “Fix the receiver endpoint” troubleshooting
step to probe the actual webhook delivery path instead of using the generic GET
curl command. Use the receiver’s documented health endpoint or a safe
authenticated POST with a contract-matching payload, and retain the existing
timeout and status verification.
- Around line 139-142: Make the RUNBOOK.md command examples copy-paste runnable
by adding validated variable setup: at RUNBOOK.md lines 139-142 define
STELLAR_RPC_URL with required-value validation before the ledger query; at lines
169-169 validate the ledger sequence before exporting it; at lines 201-206
define and validate the webhook URL and ADMIN_TOKEN; at line 266 replace
/path/to/streams.db with the actual database path or explicit substitution
instructions; at lines 289-292 and 295-296 reuse the validated RPC URL; and at
lines 319-320 replace the RPC URL and contract-key placeholders with executable
values or explicit substitution instructions.
- Around line 259-262: Configure the wal_autocheckpoint pragma in the else
branch of the SQLite connection setup in db.ts alongside the existing db.pragma
calls, using the documented threshold. Update the RUNBOOK remediation command
and wording to reference the application’s configured threshold rather than a
transient sqlite3 CLI connection.
- Around line 156-157: Update the network verification curl command in
RUNBOOK.md to use a JSON-RPC POST invoking the getHealth method instead of
requesting the /health path. Preserve the existing STELLAR_RPC_URL endpoint and
timeout while documenting the standard JSON-RPC request format.
- Around line 321-322: Update the RUNBOOK.md contract verification example to
remove the unsupported getContractData method and use the native
getLedgerEntries RPC request with the contract’s encoded ledger key, or the
repository’s established CLI/helper command. Preserve the JSON-RPC and jq
result-display structure while documenting the supported lookup flow.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 265499bd-34c7-454c-99f3-10bf72ffc6a0
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (7)
.github/PULL_REQUEST_TEMPLATE.md.husky/commit-msg.release-please-manifest.jsonRUNBOOK.mdcommitlint.config.jspackage.jsonrelease-please-config.json
| "contracts": { | ||
| "release-type": "simple", | ||
| "include-component-in-tag": true, | ||
| "component": "contracts" |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
for file in contracts/version.txt contracts/CHANGELOG.md; do
test -f "$file" || {
echo "Missing required Release Please file: $file"
exit 1
}
doneRepository: ritik4ever/stellar-stream
Length of output: 223
🏁 Script executed:
#!/bin/bash
set -u
echo "== candidate files =="
git ls-files | rg '(^|/)contracts/((version\.txt|CHANGELOG\.md)|package\.json)$|release-please-config\.json|release-please\.json|version\.txt$|CHANGELOG\.md$' || true
echo
echo "== release-please config relevant section =="
python3 - <<'PY'
from pathlib import Path
p=Path('release-please-config.json')
if p.exists():
print(p.read_text())
else:
print("release-please-config.json not found")
PY
echo
echo "== locate version.txt files =="
python3 - <<'PY'
from pathlib import Path
for f in Path('.').rglob('version.txt'):
if any(part.startswith('.') for part in f.parts):
continue
print(f)
PYRepository: ritik4ever/stellar-stream
Length of output: 2123
Add the version source file for contracts.
contracts is configured with release-type: simple, but the repository has no release-files override and no version.txt under contracts. Add contracts/version.txt or change contracts to point at an existing package version source.
[low_effort иhigh_reward]
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@release-please-config.json` around lines 26 - 29, Add the missing contracts
version source by creating contracts/version.txt with the current package
version, or update the contracts entry in release-please-config.json to
reference an existing version file. Ensure the release-type simple configuration
has a valid version source.
Source: MCP tools
| "initial-version": "1.0.0", | ||
| "bootstrap-sha": "HEAD" |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
sha=$(jq -r '."bootstrap-sha"' release-please-config.json)
[[ "$sha" =~ ^[0-9a-fA-F]{40}$ ]] || {
echo "bootstrap-sha must be a full 40-character commit SHA"
exit 1
}Repository: ritik4ever/stellar-stream
Length of output: 216
🌐 Web query:
Release Please manifest-releaser bootstrap-sha HEAD commit SHA
💡 Result:
In Release Please, the "bootstrap-sha" configuration is an optional, top-level setting used during the initial setup of a repository to control how far back the tool looks for conventional commits when generating the first release pull request [1][2][3]. Key details regarding "bootstrap-sha": * Purpose: It tells Release Please to stop collecting commits at a specific point in your history [1][2]. You should choose a commit SHA that is one commit earlier than the first commit you want to include in your changelog [1][4]. * Requirement: It must be a full commit SHA [2]. * Lifecycle: This setting is only applicable and intended for use when running Release Please for the first time [1][2]. Once a Release Please-generated pull request has been merged, this configuration value is ignored for all subsequent runs and should be removed from your config file [1][2]. * Configuration: It is specified in your release-please-config.json file [2][5]. Example configuration: { "bootstrap-sha": "your-full-commit-sha-here", "packages": { ".": {} } } If you do not provide a "bootstrap-sha" when initializing a new repository without existing releases, Release Please will generally look back through the commit history or default to an initial version (e.g., 0.1.0) [6]. Using a manifest config (a release-please-config.json and .release-please-manifest.json) is the highly recommended way to manage releases [6][7].
Citations:
- 1: https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md
- 2: https://github.com/release-please-oss/release-please/blob/master/docs/manifest-releaser.md
- 3: https://cdn.jsdelivr.net/npm/release-please@13.4.2/build/src/manifest.d.ts
- 4: https://github.com/googleapis/release-please/blob/master/docs/manifest-releaser.md
- 5: https://github.com/googleapis/release-please-action
- 6: [python] release-please creating release PRs with the wrong version googleapis/release-please#2371
- 7: https://github.com/googleapis/release-please/blob/main/docs/troubleshooting.md
Use a full commit SHA for bootstrap-sha.
bootstrap-sha must be a 40-character commit SHA, not HEAD. Set it to the appropriate full SHA, then remove the setting after the first Release Please-generated release PR is merged.
Proposed fix
- "bootstrap-sha": "HEAD"
+ "bootstrap-sha": "<full 40-character commit SHA>"🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@release-please-config.json` around lines 50 - 51, Update the bootstrap-sha
setting in the release configuration to the appropriate 40-character commit SHA
instead of HEAD. Preserve the setting until the first Release Please-generated
release PR is merged, then remove bootstrap-sha.
Source: MCP tools
| curl -s <STELLAR_RPC_URL> -X POST \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"jsonrpc":"2.0","id":1,"method":"getLatestLedger"}' | \ | ||
| jq '.result.sequence' |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Replace literal placeholders with safe, runnable variable setup.
These commands are described as copy-paste runnable, but values such as <STELLAR_RPC_URL> and <ADMIN_TOKEN> are not valid literal shell inputs; some are parsed as redirection syntax. Add a prerequisite block using validated variables such as ${STELLAR_RPC_URL:?set STELLAR_RPC_URL}, and replace /path/to/streams.db and JSON ... placeholders with concrete commands or explicit substitution instructions.
RUNBOOK.md#L139-L142: define and validate the RPC URL before the ledger query.RUNBOOK.md#L169-L169: define and validate the ledger sequence before exporting it.RUNBOOK.md#L201-L206: define the webhook URL and admin token safely.RUNBOOK.md#L266-L266: replace/path/to/streams.dbwith the actual database path.RUNBOOK.md#L289-L292: reuse the validated RPC URL.RUNBOOK.md#L295-L296: reuse the validated RPC URL.RUNBOOK.md#L319-L320: replace both the RPC URL and contract-key placeholders with executable values.
📍 Affects 1 file
RUNBOOK.md#L139-L142(this comment)RUNBOOK.md#L169-L169RUNBOOK.md#L201-L206RUNBOOK.md#L266-L266RUNBOOK.md#L289-L292RUNBOOK.md#L295-L296RUNBOOK.md#L319-L320
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@RUNBOOK.md` around lines 139 - 142, Make the RUNBOOK.md command examples
copy-paste runnable by adding validated variable setup: at RUNBOOK.md lines
139-142 define STELLAR_RPC_URL with required-value validation before the ledger
query; at lines 169-169 validate the ledger sequence before exporting it; at
lines 201-206 define and validate the webhook URL and ADMIN_TOKEN; at line 266
replace /path/to/streams.db with the actual database path or explicit
substitution instructions; at lines 289-292 and 295-296 reuse the validated RPC
URL; and at lines 319-320 replace the RPC URL and contract-key placeholders with
executable values or explicit substitution instructions.
| curl -s --max-time 5 <STELLAR_RPC_URL>/health | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
Soroban RPC health check getHealth method developers.stellar.org
💡 Result:
The getHealth method is a JSON-RPC function used to perform a general health check on a Stellar RPC node [1][2]. Note that "Soroban-RPC" was renamed to "Stellar RPC" in November 2024 [3]. When you call getHealth, the node returns a response indicating its status (typically "healthy") along with information about its ledger state [1][2]. The standard response includes the following fields [1][4]: - status: The health status of the node (e.g., "healthy") [1][2]. - latestLedger: The sequence number of the most recent ledger known to the node [1]. - latestLedgerCloseTime: The Unix timestamp (as a string) of the most recent ledger's close time [1]. - oldestLedger: The sequence number of the oldest ledger currently retained in the node's history [1]. - oldestLedgerCloseTime: The Unix timestamp (as a string) of the oldest ledger's close time [1]. - ledgerRetentionWindow: The maximum retention window configured for the node, calculated as (latestLedger - oldestLedger + 1) [1]. You can invoke this method using an HTTP POST request [1][2]. For example, using cURL [1]: curl -X POST \ -H 'Content-Type: application/json' \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "getHealth" }' \ https://soroban-testnet.stellar.org Official documentation can be found on the Stellar Developers portal at the following location: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getHealth [1].
Citations:
- 1: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getHealth
- 2: https://developers.stellar.org/docs/data/apis/rpc/admin-guide/monitoring
- 3: https://developers.stellar.org/docs/data/apis/rpc
- 4: https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/api.ts
🏁 Script executed:
#!/bin/bash
sed -n '145,162p' RUNBOOK.mdRepository: ritik4ever/stellar-stream
Length of output: 744
Use getHealth JSON-RPC in the network verification step.
The documented StoLAR RPC health check is a direct JSON-RPC POST with method getHealth; appending /health is not the standard RPC method and can report a false network failure.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@RUNBOOK.md` around lines 156 - 157, Update the network verification curl
command in RUNBOOK.md to use a JSON-RPC POST invoking the getHealth method
instead of requesting the /health path. Preserve the existing STELLAR_RPC_URL
endpoint and timeout while documenting the standard JSON-RPC request format.
| 1. **Fix the receiver endpoint:** If the downstream webhook receiver is down or returning errors, contact the receiver's operator. Verify the webhook endpoint is reachable: | ||
| ```bash | ||
| curl -s -o /dev/null -w "%{http_code}" --max-time 5 <WEBHOOK_URL> | ||
| ``` |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Probe the actual webhook delivery path, not only a GET request.
Webhook receivers commonly require authenticated POST requests with a specific payload, so this GET can report failure for a healthy receiver or success while real deliveries still fail. Use a documented health endpoint or a safe authenticated POST test matching the delivery contract.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@RUNBOOK.md` around lines 199 - 202, Update the “Fix the receiver endpoint”
troubleshooting step to probe the actual webhook delivery path instead of using
the generic GET curl command. Use the receiver’s documented health endpoint or a
safe authenticated POST with a contract-matching payload, and retain the
existing timeout and status verification.
| 4. **Inspect dead-letter payloads** to rule out malformed data: | ||
| ```bash | ||
| sqlite3 backend/data/streams.db \ | ||
| "SELECT id, payload FROM webhook_dead_letters ORDER BY created_at DESC LIMIT 5;" | \ | ||
| jq '.' |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Emit JSON before piping SQLite output to jq.
The SQLite CLI defaults to list output with pipe-separated columns, so the current pipeline is not valid JSON. Use sqlite3 -json ... (and then jq) to inspect multiple payload rows. (sqlite.org)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@RUNBOOK.md` around lines 210 - 214, Update the SQLite command in the “Inspect
dead-letter payloads” runbook step to use the CLI’s JSON output mode before
piping results to jq, while preserving the existing query and row limit.
| 3. **Set `PRAGMA wal_autocheckpoint`** to tune checkpoint frequency (default: 1000 pages). For write-heavy workloads, lower it: | ||
| ```bash | ||
| sqlite3 backend/data/streams.db "PRAGMA wal_autocheckpoint=500;" | ||
| ``` |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Files:\n'
git ls-files | rg '(^|/)RUNBOOK\.md$|(^|/)db\.ts$|package\.json$|pnpm-lock\.yaml$|package-lock\.json$|yarn\.lock$' || true
printf '\nRUNBOOK context:\n'
if [ -f RUNBOOK.md ]; then
nl -ba RUNBOOK.md | sed -n '240,275p'
fi
printf '\nSearch sqlite open/config usages:\n'
rg -n "new Database|createConnection|sqlite|PRAGMA|wal_autocheckpoint|asyncSession" -S . --glob '!node_modules' --glob '!dist' --glob '!build' | head -200 || true
printf '\nCandidate db.ts outline/content:\n'
if [ -f db.ts ]; then
wc -l db.ts
sed -n '1,240p' db.ts
fiRepository: ritik4ever/stellar-stream
Length of output: 403
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'RUNBOOK context:\n'
awk 'NR>=240 && NR<=275 {printf "%7d %s\n", NR, $0}' RUNBOOK.md
printf '\nSearch sqlite open/config usages:\n'
rg -n "new Database|createConnection|sqlite|PRAGMA|wal_autocheckpoint|asyncSession" -S . --glob '!node_modules' --glob '!dist' --glob '!build' | head -200 || true
printf '\nbackend/src/services/db.ts content:\n'
wc -l backend/src/services/db.ts
awk '{printf "%7d %s\n", NR, $0}' backend/src/services/db.ts
printf '\nbackend package sqlite dependencies:\n'
python3 - <<'PY'
import json
p='backend/package.json'
data=json.load(open(p))
for section in ['dependencies','devDependencies']:"
print(section, data.get(section, {}))
PYRepository: ritik4ever/stellar-stream
Length of output: 45214
Configure wal_autocheckpoint during SQLite connection setup.
Running sqlite3 backend/data/streams.db "PRAGMA wal_autocheckpoint=500;" in RUNBOOK.md only affects the transient CLI connection. Add the pragma in backend/src/services/db.ts inside the else branch near the other db.pragma(...) calls, and update the remediation wording here to point at the configured threshold.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@RUNBOOK.md` around lines 259 - 262, Configure the wal_autocheckpoint pragma
in the else branch of the SQLite connection setup in db.ts alongside the
existing db.pragma calls, using the documented threshold. Update the RUNBOOK
remediation command and wording to reference the application’s configured
threshold rather than a transient sqlite3 CLI connection.
| -d '{"jsonrpc":"2.0","id":1,"method":"getContractData","params":{"contractId":"<SOROBAN_CONTRACT_ID>","key":"..."}}' | \ | ||
| jq '.result' |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== RUNBOOK context =="
sed -n '280,335p' RUNBOOK.md 2>/dev/null || true
echo
echo "== references to getContractData/getLedgerEntries =="
rg -n "getContractData|getLedgerEntries|Sorobot|Soroban|Soroban" -S .Repository: ritik4ever/stellar-stream
Length of output: 20402
🌐 Web query:
Stellar RPC API getLedgerEntries getContractData deprecated getContractData
💡 Result:
In the Stellar RPC API, the getLedgerEntries method is the active, supported endpoint for retrieving ledger data, including contract data [1][2]. The getContractData method is not a native RPC API endpoint; rather, it is a helper method provided by Stellar SDKs (such as js-stellar-sdk and js-soroban-client) that simplifies the process of querying contract storage [3][4]. There is no deprecation of getContractData as an SDK helper method; it remains a standard tool for developers to interact with contract data [3][4]. Similarly, getLedgerEntries is not deprecated; it is the primary RPC method used to fetch various types of ledger entries, including accounts, offers, and contract data [1][5]. Regarding your query about deprecation: 1. getContractData: This remains a functional helper method within the Stellar SDKs [3][4]. It functions by internally constructing the appropriate LedgerKey for contract data and calling getLedgerEntry (which in turn uses getLedgerEntries) to retrieve the value [3]. 2. getLedgerEntries: This is the current, active RPC method [1]. 3. getLedgerEntry: Note that the specific RPC endpoint getLedgerEntry has been deprecated and removed in favor of getLedgerEntries, which supports bulk requests and offers higher performance [6][7]. If you are seeing references to "deprecated" in relation to RPC endpoints, it most likely refers to the older getLedgerEntry (singular) method, which has been removed as of Stellar RPC v23.0.0 [6]. Developers should ensure they are using getLedgerEntries for all direct ledger queries [1].
Citations:
- 1: https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getLedgerEntries
- 2: https://developers.stellar.org/docs/data/apis/rpc
- 3: https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts
- 4: https://stellar.github.io/js-soroban-client/Server.html
- 5: https://developers.stellar.org/docs/data/apis/migrate-from-horizon-to-rpc
- 6: https://github.com/stellar/stellar-rpc/releases/tag/v23.0.0
- 7: Replace
getLedgerEntries()with a proxy to Core's/getledgerentry. stellar/stellar-rpc#269
Use the current Soroban RPC ledger-entry lookup for contract verification.
getContractData is not a native RPC method; getLedgerEntries is the supported direct RPC endpoint for contract storage. Replace this example with a ledger-entry request using the contract’s encoded ledger key, or a repository-specific CLI/helper command.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@RUNBOOK.md` around lines 321 - 322, Update the RUNBOOK.md contract
verification example to remove the unsupported getContractData method and use
the native getLedgerEntries RPC request with the contract’s encoded ledger key,
or the repository’s established CLI/helper command. Preserve the JSON-RPC and jq
result-display structure while documenting the supported lookup flow.
2 participants
Summary
Issue #792 — RUNBOOK Expansion
Added 4 new operational playbooks:
Each playbook includes symptoms, copy-paste-runnable diagnosis commands, and remediation steps.
Issue #805 — CHANGELOG Automation via release-please
commitlint.config.js— enforces conventional commits (feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert).husky/commit-msg— git hook blocking non-conforming commitsrelease-please-config.json— multi-package config (root, backend, frontend, contracts).release-please-manifest.json— version trackingTesting done
Related issues
Closes #792
Closes #805
Summary by CodeRabbit
Documentation
Chores