111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```text
|
|
.
|
|
├── 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
make validate
|
|
make summary
|
|
```
|
|
|
|
Before push:
|
|
|
|
```bash
|
|
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.
|