docs: add AGENTS.md and companion templates per Notion standards by jreakin · Pull Request #10 · Abstract-Data/RyanData-Address-Utils

jreakin · 2026-03-19T19:54:25Z

No description provided.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

coderabbitai · 2026-03-19T19:54:32Z

Warning

Rate limit exceeded

@jreakin has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 29 minutes and 16 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ca999c35-a430-43da-b714-d3d1048219df

📥 Commits

Reviewing files that changed from the base of the PR and between 5864ff2 and 26a3b42.

📒 Files selected for processing (3)

GUARDRAILS.md
RUNBOOK.md
TESTING.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch claude/naughty-herschel

📝 Coding Plan

Generate coding plan for human review comments

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

Adds new project documentation files intended to standardize local development, testing, and operational guidance for the RyanData Address Utils codebase.

Changes:

Add TESTING.md with pytest/Hypothesis commands and testing standards.
Add RUNBOOK.md with setup steps, common operations, lint/typecheck commands, and troubleshooting.
Add GUARDRAILS.md describing development do’s/don’ts and data sensitivity rules.

Reviewed changes

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

File	Description
TESTING.md	Introduces testing commands/standards and a proposed test directory layout.
RUNBOOK.md	Adds developer runbook for setup, operations, and troubleshooting.
GUARDRAILS.md	Adds contribution guardrails and data handling guidance.

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

Copilot · 2026-03-19T19:58:02Z

GUARDRAILS.md

+# GUARDRAILS.md — RyanData-Address-Utils
+<!-- Version: 1.0.0 | Maintainer: John Eakin -->


The PR title references adding AGENTS.md and companion templates, but the provided diff only adds TESTING.md/RUNBOOK.md/GUARDRAILS.md. Please align the PR title/description with the actual changes (or include the missing files) so reviewers know what to expect.

Copilot · 2026-03-19T19:58:02Z

TESTING.md

+- **Coverage target:** 80%+ (src/)
+
+## Commands
+
+```bash
+uv run pytest                        # all tests
+uv run pytest --cov=src              # with coverage
+uv run pytest -x                     # stop on first failure
+uv run pytest -k "test_parse"        # filter by name
+uv run pytest tests/unit/            # unit tests only
+uv run pytest tests/property/        # Hypothesis tests only


The coverage command here (--cov=src) doesn't match CI, which runs pytest with --cov=src/ryandata_address_utils (see .github/workflows/tests.yml). Using the package path keeps local docs consistent with what CI reports.

Suggested change

- **Coverage target:** 80%+ (src/)

## Commands

```bash

uv run pytest # all tests

uv run pytest --cov=src # with coverage

uv run pytest -x # stop on first failure

uv run pytest -k "test_parse" # filter by name

uv run pytest tests/unit/ # unit tests only

uv run pytest tests/property/ # Hypothesis tests only

- **Coverage target:** 80%+ (src/ryandata_address_utils)

## Commands

```bash

uv run pytest # all tests

uv run pytest --cov=src/ryandata_address_utils # with coverage

uv run pytest -x # stop on first failure

uv run pytest -k "test_parse" # filter by name

uv run pytest tests/unit/ # unit tests only

uv run pytest tests/property/ # Hypothesis tests only

Copilot · 2026-03-19T19:58:03Z

TESTING.md

+uv run pytest tests/unit/            # unit tests only
+uv run pytest tests/property/        # Hypothesis tests only
+```
+
+## Test Layout
+
+```
+tests/
+├── unit/           # Pure unit tests — no I/O, no network
+├── integration/    # Tests that hit the filesystem or pandas
+├── property/       # Hypothesis property-based tests
+└── conftest.py     # Shared fixtures
+```


These commands and the test tree below assume tests/unit/, tests/integration/, and tests/property/, but the current repo uses a flat tests/ layout (e.g., tests/test_*.py plus tests/strategies.py). Please update the suggested commands/layout to match the actual structure so the instructions work as written.

Copilot · 2026-03-19T19:58:03Z

RUNBOOK.md

+| Symptom | Fix |
+|---------|-----|
+| `ModuleNotFoundError` | Run `uv sync` |


The troubleshooting table isn't valid Markdown because of the double leading pipes (|| ...). This won’t render as a table in most viewers; switch to standard table syntax (| header row + separator row) so it formats correctly on GitHub.

Copilot · 2026-03-19T19:58:03Z

RUNBOOK.md

+|---------|-----|
+| `ModuleNotFoundError` | Run `uv sync` |
+| Parser returns `None` | Check address format; try `usaddress` backend |
+| Shapefile import fails | Ensure `geopandas` extras installed: `uv sync --extra geo` |


uv sync --extra geo won't work as written because pyproject.toml currently defines only the pandas optional dependency group (no geo extra). Either add a geo extra (e.g., geopandas-related deps) or update the runbook to use an existing option such as --extra pandas or --all-extras.

Suggested change

| Shapefile import fails | Ensure `geopandas` extras installed: `uv sync --extra geo` |

| Shapefile import fails | Ensure `geopandas` extras installed: `uv sync --extra pandas` |

Copilot · 2026-03-19T19:58:03Z

RUNBOOK.md

+| Symptom | Fix |
+|---------|-----|
+| `ModuleNotFoundError` | Run `uv sync` |
+| Parser returns `None` | Check address format; try `usaddress` backend |


The symptom/diagnostic here is misleading: AddressService.parse() returns a ParseResult, not None, and the default parser type is already "usaddress" (ParserFactory default). Consider updating this row to describe the actual failure mode (e.g., result.is_parsed false / result.is_valid false) and the recommended next step.

Suggested change

| Parser returns `None` | Check address format; try `usaddress` backend |

| `AddressService.parse()` returns a `ParseResult` with `result.is_parsed` or `result.is_valid` set to `False` | Check address format and clean up input; inspect parse errors and adjust or retry with a different parser backend if available |

docs: add AGENTS.md and companion templates per Notion standards

26a3b42

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings March 19, 2026 19:54

jreakin merged commit f18ac93 into main Mar 19, 2026
4 of 9 checks passed

jreakin deleted the claude/naughty-herschel branch March 19, 2026 19:54

Copilot started reviewing on behalf of jreakin March 19, 2026 19:54 View session

Copilot AI reviewed Mar 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add AGENTS.md and companion templates per Notion standards#10

docs: add AGENTS.md and companion templates per Notion standards#10
jreakin merged 1 commit intomainfrom
claude/naughty-herschel

jreakin commented Mar 19, 2026

Uh oh!

coderabbitai bot commented Mar 19, 2026

Rate limit exceeded

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 19, 2026

Uh oh!

Copilot AI Mar 19, 2026

Uh oh!

Copilot AI Mar 19, 2026

Uh oh!

Copilot AI Mar 19, 2026

Uh oh!

Copilot AI Mar 19, 2026

Uh oh!

Copilot AI Mar 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		# GUARDRAILS.md — RyanData-Address-Utils
		<!-- Version: 1.0.0 \| Maintainer: John Eakin -->

	\| Shapefile import fails \| Ensure `geopandas` extras installed: `uv sync --extra geo` \|
	\| Shapefile import fails \| Ensure `geopandas` extras installed: `uv sync --extra pandas` \|

	\| Parser returns `None` \| Check address format; try `usaddress` backend \|
	\| `AddressService.parse()` returns a `ParseResult` with `result.is_parsed` or `result.is_valid` set to `False` \| Check address format and clean up input; inspect parse errors and adjust or retry with a different parser backend if available \|

Conversation

jreakin commented Mar 19, 2026

Uh oh!

coderabbitai bot commented Mar 19, 2026

Rate limit exceeded

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants