documentation-docusaurus/references/research-address-book-repositories.md

Research Address-Book Repositories

Use this pattern when a Gitea repository is intended to map a broad ecosystem, organization network, infrastructure landscape, or other changing domain.

Design principle

Start with an address book of authoritative directories and coordinating bodies, not an attempted exhaustive list of every participant. Large ecosystems change too quickly for a hand-maintained flat inventory. Anchor later ingestion to official registries, public directories, and primary sources.

Separate four concerns:

1. Human navigation and concise summaries.
2. Canonical machine-readable records.
3. Method, taxonomy, and analytical findings.
4. Unverified leads and future research.

Recommended structure

.
├── README.md
├── address-book/
│   ├── README.md
│   └── <category>.md
├── data/
│   ├── README.md
│   └── entities.csv
├── docs/
│   ├── 01-scope-and-method.md
│   ├── 02-first-round-investigation.md
│   └── 03-taxonomy.md
├── research/
│   └── next-round.md
├── scripts/
│   └── validate.py
├── sources/
│   └── README.md
├── CONTRIBUTING.md
└── Makefile

Keep the top level small and obvious. Number only documents that have a reading sequence. Prefer category pages over one giant address-book document.

Round-1 data model

CSV is a strong first format because it is Git-readable, spreadsheet-compatible, and dependency-free. Useful columns:

id,name,category,scope,region,homepage,directory_url,role,source_url,status,verified_at,notes

Conventions:

• id: stable lowercase kebab-case; never recycle IDs.
• category: controlled taxonomy, based on function rather than assumed hierarchy.
• scope: distinguish global, regional, and regional-community scope.
• region: service or community coverage, not merely headquarters.
• directory_url: best public discovery, contact, membership, registry, or data entry point.
• source_url: primary evidence for the role claim.
• status: verified, partial, lead, or stale.
• verified_at: UTC date in YYYY-MM-DD.
• notes: caveats about automated access, completeness, ownership, or interpretation.

Move to versioned JSON/YAML records only when nested relationships, source merges, or repeated attributes make CSV inadequate. Do not add a database just for presentation.

Research method

1. State the research question and explicit boundary.
2. Build a functional taxonomy; do not force decentralized ecosystems into a false parent/child hierarchy.
3. Identify globally or regionally authoritative directories and coordinating bodies.
4. Prefer official registries, APIs, standards bodies, and operator-maintained sources.
5. Verify URL reachability, but distinguish transport success from factual proof.
6. Put canonical entries in structured data; keep hypotheses in research/.
7. Write a first-round synthesis explaining findings, evidence limits, and missing coverage.
8. Define the next research rounds before adding automation.

Provenance and contact safety

• Prefer public institutional and role-based contact points.
• Do not publish private personal data, credentials, or member-only incident contacts.
• A registry record does not necessarily establish current operator, owner, or beneficial controller.
• Community-maintained databases and measurement collectors expose partial viewpoints; document coverage caveats.
• A 403 from an automated client may be an access-policy caveat, not evidence that the official URL or entity is invalid. Record the caveat and use browser/manual verification when appropriate.

Validation

Provide a standard-library-only validator where practical. Check:

• exact required columns;
• non-empty required fields;
• unique and well-formed IDs;
• controlled taxonomy/status values;
• HTTPS URLs;
• parseable, non-future verification dates;
• presence of required orientation documents.

Expose predictable commands:

make validate
make summary

Before push:

git diff --cached --check
make validate

After push, verify both the Git ref and at least one distinctive remote artifact using the authenticated Gitea API. A successful push message is useful evidence, but authenticated readback confirms the requested content rather than only the ref update.