What problem does this solve?
Right now there are two ways to add a public place, and both expect a level of
technical or GitHub familiarity that the general public does not have:
- The in-app "Suggest a place" dialog collects details, then opens a prefilled
GitHub issue. Submitting still needs a GitHub account, and the result is an
issue, not a merged place.
- The "Add a place" card on the /contribute page tells a contributor to fork
the repository, hand-edit a JSON file, obey an id-convention, and open a pull
request. That is a wall for anyone who does not know Git, JSON, or GitHub.
For a crowdsourced map whose target audience is students (the general public),
the direct JSON contribution pipeline is a bottleneck. The problem: contributing
a place should not require knowing Git, editing JSON, or even having a GitHub
account.
Proposed solution
Build a pipeline that takes a minimal, friendly submission and turns it into a
reviewed pull request, without the submitter touching the repository.
- Refine the in-app "Suggest a place" dialog (name, Google Maps link, place
type) so it collects just what a non-technical person can confidently answer.
- Overhaul the "Add a place" card on /contribute so it leads with this friendly
form instead of the fork-and-edit-JSON instructions.
- A backend program reads the submission, extrapolates what it can from the
Google Maps link (latitude and longitude from the URL), writes the record to
the correct data file, and opens a pull request back to the repository.
Form fields (minimum viable set)
- Place name
- Google Maps link (latitude/longitude parsed from the URL)
- Place type (dropdown, matches the existing type enum)
- City (manual field, with the existing city suggestions)
- Contributor name (optional)
- Note or source (optional, kept for v1 so a contributor can quietly attest
rating / review count / source, which the existing quality gate wants)
The backend infers the rest:
- The record id is derived from the existing per-city file convention (for
example, continuing thn-library-04 after thn-library-03).
- The target file is chosen from the place type.
- Address stays blank unless the contributor adds it in a note.
Validation
Schema and format validation are automated (the submission must map to a valid
type and pass the existing npm run validate rules). Distinguishing whether a
submission is genuinely what it claims to be, for example an airport that says
it is a library, is a human judgment; automation catches malformed records but
a reviewer still decides what is real. Semantic truth-checking can be explored
later.
Definition of done
A non-technical user can go to the map or /contribute, enter a place name, a
Google Maps link, and a type, submit, and the place ends up in a reviewed pull
request in the repository, without forking, editing JSON, or using GitHub.
Alternatives considered
- Keep the current GitHub-issue and fork-and-edit-JSON paths as the only ways
to contribute. Rejected as out of step with a general-public audience.
- Scrape Google ratings/review counts automatically to auto-approve places.
Rejected: it is not reliable, risks Google terms, and would bypass the
reviewed-in-the-open promise.
Open questions for the maintainer
These are intentionally left open because the right answer depends on hosting,
cost, and review posture. Any of them can be decided during scoping.
- Backend architecture: a GitHub Actions workflow triggered off submissions, a
standalone backend service, or a contributor-bot-style integration?
- Contributor attribution: a free-text name field on the record, or a GitHub
identity tied to the commit?
- Submission contract: does the form emit a machine-parseable issue body, or
POST to an API endpoint directly?
- Quality-gate handling under automation: how much of the rating / review /
source gate stays human vs. mechanical?
Explicitly out of scope for v1
- Reverse geocoding to auto-fill city and address from the link (city is manual,
coordinates are parsed from the URL).
- Semantic truth-checking (airport vs library) beyond what a human review
already provides.
- Building rate-limiting or anti-abuse infrastructure up front; the maintainer
review is the shield, and submissions stay simple.
- Removing the raw GitHub contribution path. It stays as a documented fallback
for contributors who prefer it.
Checklist
What problem does this solve?
Right now there are two ways to add a public place, and both expect a level of
technical or GitHub familiarity that the general public does not have:
GitHub issue. Submitting still needs a GitHub account, and the result is an
issue, not a merged place.
the repository, hand-edit a JSON file, obey an id-convention, and open a pull
request. That is a wall for anyone who does not know Git, JSON, or GitHub.
For a crowdsourced map whose target audience is students (the general public),
the direct JSON contribution pipeline is a bottleneck. The problem: contributing
a place should not require knowing Git, editing JSON, or even having a GitHub
account.
Proposed solution
Build a pipeline that takes a minimal, friendly submission and turns it into a
reviewed pull request, without the submitter touching the repository.
type) so it collects just what a non-technical person can confidently answer.
form instead of the fork-and-edit-JSON instructions.
Google Maps link (latitude and longitude from the URL), writes the record to
the correct data file, and opens a pull request back to the repository.
Form fields (minimum viable set)
rating / review count / source, which the existing quality gate wants)
The backend infers the rest:
example, continuing
thn-library-04afterthn-library-03).Validation
Schema and format validation are automated (the submission must map to a valid
type and pass the existing
npm run validaterules). Distinguishing whether asubmission is genuinely what it claims to be, for example an airport that says
it is a library, is a human judgment; automation catches malformed records but
a reviewer still decides what is real. Semantic truth-checking can be explored
later.
Definition of done
A non-technical user can go to the map or /contribute, enter a place name, a
Google Maps link, and a type, submit, and the place ends up in a reviewed pull
request in the repository, without forking, editing JSON, or using GitHub.
Alternatives considered
to contribute. Rejected as out of step with a general-public audience.
Rejected: it is not reliable, risks Google terms, and would bypass the
reviewed-in-the-open promise.
Open questions for the maintainer
These are intentionally left open because the right answer depends on hosting,
cost, and review posture. Any of them can be decided during scoping.
standalone backend service, or a contributor-bot-style integration?
identity tied to the commit?
POST to an API endpoint directly?
source gate stays human vs. mechanical?
Explicitly out of scope for v1
coordinates are parsed from the URL).
already provides.
review is the shield, and submissions stay simple.
for contributors who prefer it.
Checklist