Add contributing guide with LLM quick start instructions by leofelix077 · Pull Request #302 · stellar/freighter-backend

leofelix077 · 2026-04-08T17:22:08Z

Skill Eval: `freighter-backend-dev-setup` — Benchmark Report

Date: 2026-04-08
Iterations: 4
Repo: stellar/freighter-backend
Model: Claude Opus 4.6
Prompt: "I just cloned freighter-backend and want to run it locally."

Summary

Metric	With Skill	Without Skill	Delta
Pass rate	93%	65%	+28pp

The skill provides consistent, structured output with correct env var guidance.
The baseline often misses the in-memory dev mode and Redis requirement details.

Assertion Results (aggregated across 4 iterations)

#	Assertion	With Skill	Without Skill
1	Checks Node.js version (>= 25.3.0)	4/4 (100%)	3/4 (75%)
2	Checks Yarn version	4/4 (100%)	3/4 (75%)
3	Checks Docker availability	4/4 (100%)	4/4 (100%)
4	Detects .env missing	4/4 (100%)	4/4 (100%)
5	Lists required env vars (MODE, HOSTNAME, REDIS_PORT)	4/4 (100%)	2/4 (50%)
6	Explains dev mode (in-memory, no Redis needed)	3/4 (75%)	1/4 (25%)
7	Explains production mode (requires Redis)	4/4 (100%)	3/4 (75%)
8	Mentions docker compose for Redis	4/4 (100%)	2/4 (50%)
9	Structured prerequisites table	3/4 (75%)	1/4 (25%)
10	Produces actionable summary	4/4 (100%)	2/4 (50%)
	Overall	37/40 (93%)	26/40 (65%)

Analysis

The skill's main value is documenting the two run modes (dev with in-memory
store vs production with Redis) — this distinction is not obvious from
package.json alone. The baseline frequently missed the in-memory dev mode.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds contributor-facing setup documentation (including an LLM-oriented quick start) to make local development setup more reliable and to clarify dev (in-memory) vs production (Redis) run modes.

Changes:

Added CONTRIBUTING.md with prerequisites, manual setup steps, env var guidance, and key commands.
Added LLM-QUICK-START.md to guide an LLM assistant through prerequisite checks, env setup, run, and verification.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
LLM-QUICK-START.md	Step-by-step LLM-oriented local setup guide, including prerequisites, `.env` creation, and dev/prod run commands.
CONTRIBUTING.md	New contributing guide consolidating prerequisites, setup instructions, env var overview, conventions, and PR expectations.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-08T17:28:09Z

LLM-QUICK-START.md

+For local development with `yarn start`, most values can stay as `not-set` — the
+app uses an in-memory store. Set these for basic operation:
+
+| Variable              | Value for local dev       |
+| --------------------- | ------------------------- |
+| `MODE`                | `development`             |
+| `HOSTNAME`            | `localhost`               |
+| `REDIS_PORT`          | `6379`                    |
+| `REDIS_CONNECTION_NAME` | `freighter-dev`         |


The setup flow implies cp .env-EXAMPLE .env is sufficient, but the app currently hard-requires additional env keys that are not present in .env-EXAMPLE (notably FREIGHTER_RPC_PUBNET_URL and FREIGHTER_TRUST_PROXY_RANGE via src/config.ts’s ENV_KEYS check). Following these instructions will fail with an invalid/missing env error unless those keys are added. Please either (a) update this guide to explicitly add/set those missing variables, or (b) update .env-EXAMPLE (ideally in this PR) so copy/paste setup works as documented.

Suggested change

For local development with `yarn start`, most values can stay as `not-set` — the

app uses an in-memory store. Set these for basic operation:

| Variable | Value for local dev |

| --------------------- | ------------------------- |

| `MODE` | `development` |

| `HOSTNAME` | `localhost` |

| `REDIS_PORT` | `6379` |

| `REDIS_CONNECTION_NAME` | `freighter-dev` |

Copying `.env-EXAMPLE` is only the starting point. Before the app will boot,

make sure all required environment variables are set in `.env`.

For local development with `yarn start`, most values can stay as `not-set` — the

app uses an in-memory store. Set these for basic operation:

| Variable | Value for local dev |

| ------------------------------ | ------------------------------------ |

| `MODE` | `development` |

| `HOSTNAME` | `localhost` |

| `REDIS_PORT` | `6379` |

| `REDIS_CONNECTION_NAME` | `freighter-dev` |

| `FREIGHTER_RPC_PUBNET_URL` | Your pubnet RPC URL |

| `FREIGHTER_TRUST_PROXY_RANGE` | `127.0.0.1/32` |

Copilot · 2026-04-08T17:28:09Z

CONTRIBUTING.md

+```bash
+git clone https://github.com/stellar/freighter-backend.git
+cd freighter-backend
+cp .env-EXAMPLE .env    # Then fill in values (see below)
+yarn install
+yarn start              # Dev mode (uses in-memory store, no Redis needed)
+```


docker compose up -d + cp .env-EXAMPLE .env is described as a working starting point, but the runtime env validation currently requires additional keys that are not present in .env-EXAMPLE (e.g. FREIGHTER_RPC_PUBNET_URL and FREIGHTER_TRUST_PROXY_RANGE in src/config.ts). As written, a fresh clone will error on startup unless the contributor adds those variables. Please document the missing required variables here (or update .env-EXAMPLE in the same PR) so the manual setup is actually runnable.

Copilot · 2026-04-08T17:28:10Z

CONTRIBUTING.md

+| Variable            | Purpose                                        | How to obtain                       |
+| ------------------- | ---------------------------------------------- | ----------------------------------- |
+| `MODE`              | `development` or `production`                  | Set to `development` for local dev  |
+| `HOSTNAME`          | Server hostname                                | `localhost`                         |


HOSTNAME is described as the server hostname, but in the current code it’s used as the Redis host (and passed into Redis-backed workers). Consider renaming the description to something like “Redis hostname”/“Redis host” to avoid contributors setting this incorrectly.

Suggested change

| `HOSTNAME` | Server hostname | `localhost` |

| `HOSTNAME` | Redis hostname | `localhost` |

Copilot · 2026-04-08T17:28:10Z

CONTRIBUTING.md

+| `AUTH_EMAIL` / `AUTH_PASS` | Mercury indexer auth    | Only needed if `USE_MERCURY=true`    |
+| `SENTRY_KEY`          | Error tracking             | Leave as `not-set` for local dev     |
+| `BLOCKAID_KEY`        | Transaction scanning       | Leave as `not-set` for local dev     |
+| `COINBASE_API_KEY/SECRET` | Pricing data           | Leave as `not-set` for local dev     |


COINBASE_API_KEY/SECRET doesn’t match the actual env var names in .env-EXAMPLE / config (COINBASE_API_KEY and COINBASE_API_SECRET). Please update the docs to list the exact variable names so contributors can copy/paste them correctly.

Suggested change

| `COINBASE_API_KEY/SECRET` | Pricing data | Leave as `not-set` for local dev |

| `COINBASE_API_KEY` / `COINBASE_API_SECRET` | Pricing data | Leave as `not-set` for local dev |

Node v25.3.0 exists (released Oct 2025). The earlier change to >=18.0.0 was incorrect.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-08T18:56:48Z

.env-EXAMPLE

 COINBASE_API_KEY=not-set
 COINBASE_API_SECRET=not-set
 FREIGHTER_HORIZON_URL=not-set
+FREIGHTER_TRUST_PROXY_RANGE=not-set


FREIGHTER_TRUST_PROXY_RANGE=not-set will be treated as a non-empty value and passed into proxy-addr.compile(...) via initApiServer, which will throw on an invalid range string and prevent the server from starting. Use an empty value (so trustProxy is unset) or a valid CIDR/range such as 127.0.0.1/32 as the default in .env-EXAMPLE.

Suggested change

FREIGHTER_TRUST_PROXY_RANGE=not-set

FREIGHTER_TRUST_PROXY_RANGE=

Copilot · 2026-04-08T18:56:49Z

LLM-QUICK-START.md

+Copying `.env-EXAMPLE` is only the starting point. Before the app will boot,
+make sure all required environment variables are set in `.env`.
+
+For local development with `yarn start`, most values can stay as `not-set` — the
+app uses an in-memory store. Set these for basic operation:


This section says the app won't boot until all required env vars are set, but the code only requires keys to exist; with .env-EXAMPLE the service can start even with placeholder values. More importantly, FREIGHTER_TRUST_PROXY_RANGE cannot be left as not-set because it will be compiled into trustProxy and can crash startup—call out the valid/empty value requirement explicitly here.

Suggested change

Copying `.env-EXAMPLE` is only the starting point. Before the app will boot,

make sure all required environment variables are set in `.env`.

For local development with `yarn start`, most values can stay as `not-set` — the

app uses an in-memory store. Set these for basic operation:

Copying `.env-EXAMPLE` is only the starting point. It ensures the expected keys

exist in `.env`, but it does **not** guarantee every value is valid for startup.

With placeholder values from `.env-EXAMPLE`, the service may still start in some

cases.

For local development with `yarn start`, most values can stay as `not-set` — the

app uses an in-memory store. However, `FREIGHTER_TRUST_PROXY_RANGE` must **not**

be left as `not-set`: set it to a valid proxy/CIDR value for local development

(for example `127.0.0.1/32`), or leave it empty if you do not want to trust a

proxy. Set these for basic operation:

Copilot · 2026-04-08T18:56:49Z

LLM-QUICK-START.md

+docker --version 2>&1 || which docker
+
+# Docker Compose
+docker compose version 2>&1 || which docker-compose


The Docker Compose prerequisite check falls back to which docker-compose, which only prints a path (not a version) and doesn't verify Compose is usable. Consider falling back to docker-compose --version when docker compose version fails.

Suggested change

docker compose version 2>&1 || which docker-compose

docker compose version 2>&1 || docker-compose --version 2>&1

Copilot · 2026-04-08T18:56:49Z

CONTRIBUTING.md

+### Environment Variables
+
+Copy `.env-EXAMPLE` to `.env`. For local development with `yarn start`, most
+variables can be left as `not-set` — the app uses an in-memory store by default.


This implies most variables can remain not-set for yarn start, but at least FREIGHTER_TRUST_PROXY_RANGE must be empty or a valid proxy-addr range (a literal not-set will be treated as configured and can crash startup). It would help to list any exceptions explicitly so a straight copy of .env-EXAMPLE leads to a bootable dev setup.

Suggested change

variables can be left as `not-set` — the app uses an in-memory store by default.

variables can remain `not-set` because the app uses an in-memory store by

default. **Exception:** `FREIGHTER_TRUST_PROXY_RANGE` must be left empty or set

to a valid proxy-addr range such as `127.0.0.1/32` for local dev; do not leave

it as the literal string `not-set`.

Add contributing guide with LLM quick start instructions

e855f38

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

leofelix077 self-assigned this Apr 8, 2026

Copilot AI review requested due to automatic review settings April 8, 2026 17:22

Copilot started reviewing on behalf of leofelix077 April 8, 2026 17:22 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

leofelix077 added the documentation Improvements or additions to documentation label Apr 8, 2026

leofelix077 added 3 commits April 8, 2026 14:51

Update contributing.md file information

fa2d2d7

Update contributing.md file information

5c37c4e

Revert Node.js version requirement to >=25.3.0

02253af

Node v25.3.0 exists (released Oct 2025). The earlier change to >=18.0.0 was incorrect.

leofelix077 requested a review from Copilot April 8, 2026 18:52

Copilot started reviewing on behalf of leofelix077 April 8, 2026 18:52 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

fix adjustments from copilot review

05a342c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add contributing guide with LLM quick start instructions#302

Add contributing guide with LLM quick start instructions#302
leofelix077 wants to merge 5 commits intomainfrom
docs/add-contributing-guide

leofelix077 commented Apr 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 8, 2026

Uh oh!

Copilot AI Apr 8, 2026

Uh oh!

Copilot AI Apr 8, 2026

Uh oh!

Copilot AI Apr 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 8, 2026

Uh oh!

Copilot AI Apr 8, 2026

Uh oh!

Copilot AI Apr 8, 2026

Uh oh!

Copilot AI Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	\| `HOSTNAME` \| Server hostname \| `localhost` \|
	\| `HOSTNAME` \| Redis hostname \| `localhost` \|

	\| `COINBASE_API_KEY/SECRET` \| Pricing data \| Leave as `not-set` for local dev \|
	\| `COINBASE_API_KEY` / `COINBASE_API_SECRET` \| Pricing data \| Leave as `not-set` for local dev \|

	FREIGHTER_TRUST_PROXY_RANGE=not-set
	FREIGHTER_TRUST_PROXY_RANGE=

-Copying `.env-EXAMPLE` is only the starting point. Before the app will boot,
-make sure all required environment variables are set in `.env`.
-For local development with `yarn start`, most values can stay as `not-set` — the
-app uses an in-memory store. Set these for basic operation:
+Copying `.env-EXAMPLE` is only the starting point. It ensures the expected keys
+exist in `.env`, but it does **not** guarantee every value is valid for startup.
+With placeholder values from `.env-EXAMPLE`, the service may still start in some
+cases.
+For local development with `yarn start`, most values can stay as `not-set` — the
+app uses an in-memory store. However, `FREIGHTER_TRUST_PROXY_RANGE` must **not**
+be left as `not-set`: set it to a valid proxy/CIDR value for local development
+(for example `127.0.0.1/32`), or leave it empty if you do not want to trust a
+proxy. Set these for basic operation:

	docker compose version 2>&1 \|\| which docker-compose
	docker compose version 2>&1 \|\| docker-compose --version 2>&1

-variables can be left as `not-set` — the app uses an in-memory store by default.
+variables can remain `not-set` because the app uses an in-memory store by
+default. **Exception:** `FREIGHTER_TRUST_PROXY_RANGE` must be left empty or set
+to a valid proxy-addr range such as `127.0.0.1/32` for local dev; do not leave
+it as the literal string `not-set`.

Conversation

leofelix077 commented Apr 8, 2026

Skill Eval: freighter-backend-dev-setup — Benchmark Report

Summary

Assertion Results (aggregated across 4 iterations)

Analysis

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Skill Eval: `freighter-backend-dev-setup` — Benchmark Report