Add repo-local onboarding guide as supplement to broader CultureBotAI onboarding#8
Add repo-local onboarding guide as supplement to broader CultureBotAI onboarding#8
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a repo-local onboarding and setup guide for CultureBotAI/auto-term-catalog, positioned as a supplement to broader CultureBotAI onboarding, with emphasis on using Codex CLI and on reproducible repo scaffolding expectations.
Changes:
- Introduces a new intern onboarding + repo setup guide covering Homebrew/Node/Codex CLI install and LBL ChatGPT sign-in flow.
- Documents the repo’s current gaps (no pyproject/pin/lock/tests/CI; hard-coded paths) and recommends a Python/tooling baseline (Python 3.11 +
uv+pytest+ruff). - Provides a “day 1” checklist and troubleshooting section aimed at new contributors.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Repository covered here: | ||
|
|
||
| - `CultureBotAI/auto-term-catalog` | ||
| - Local checkout: `/home/mark/gitrepos/auto-term-catalog` |
There was a problem hiding this comment.
The doc hard-codes a specific contributor’s local checkout path (/home/mark/...). For a repo-local onboarding guide, this will confuse new users and may leak personal environment details. Suggest switching to a generic example path (e.g., ~/gitrepos/auto-term-catalog) and/or describing the directory choice without a concrete user-specific absolute path.
| - Local checkout: `/home/mark/gitrepos/auto-term-catalog` | |
| - Local checkout example: `~/gitrepos/auto-term-catalog` |
| ## Part 1: Install the local tools | ||
|
|
||
| ## Why this guide exists | ||
|
|
There was a problem hiding this comment.
Heading structure: ## Part 1: Install the local tools is immediately followed by ## Why this guide exists at the same heading level, so “Part 1” doesn’t actually contain its intended subsections in the rendered outline/TOC. Consider making the “Part” headings the section parents (H2) and the content under them H3 (or remove the “Part” headers) for a consistent document structure.
|
|
||
| This repo needs a repo-local guide because two separate things are true at once: | ||
|
|
||
| - Marcin's ecosystem already has broader onboarding materials. |
There was a problem hiding this comment.
The text references “Marcin's ecosystem” without context or a link. For new interns, this is ambiguous; consider rephrasing to “the broader CultureBotAI onboarding materials” and linking to the canonical onboarding resource if one exists.
| - Marcin's ecosystem already has broader onboarding materials. | |
| - The broader CultureBotAI onboarding materials already exist. |
| - The code in this repo does not need 3.12-only or 3.13-only features. | ||
| - A lightweight data-processing repo benefits more from stability than from chasing the newest interpreter. | ||
|
|
||
| I would not start this repo on 3.9 or 3.10 now, and I would not make 3.13 the baseline for student onboarding unless the rest of Marcin's repos are already standardized there. |
There was a problem hiding this comment.
This sentence depends on the reader knowing who “Marcin” is and which repos are being referenced. Consider rewording to refer to “other CultureBotAI repos” (or a specific linked set of repos) so the guidance is understandable to someone onboarding fresh to the org.
| I would not start this repo on 3.9 or 3.10 now, and I would not make 3.13 the baseline for student onboarding unless the rest of Marcin's repos are already standardized there. | |
| I would not start this repo on 3.9 or 3.10 now, and I would not make 3.13 the baseline for student onboarding unless other CultureBotAI repos are already standardized there. |
|
|
||
| That is expected in the current repo, because the main script contains a hard-coded path: | ||
|
|
||
| - `/Users/lukewang/Downloads/chemical_utilization_cborg_gpt5_20250819_113045.yaml` |
There was a problem hiding this comment.
The troubleshooting section includes a real absolute path with a specific username (/Users/lukewang/...). Even as an example of a hard-coded path, it’s better to redact/parameterize usernames (e.g., /Users/<username>/Downloads/... or ~/Downloads/...) to avoid embedding personal identifiers in docs and to keep the example portable.
| - `/Users/lukewang/Downloads/chemical_utilization_cborg_gpt5_20250819_113045.yaml` | |
| - `~/Downloads/chemical_utilization_cborg_gpt5_20250819_113045.yaml` |
Summary
This PR adds a repo-local onboarding and setup guide for
auto-term-catalog.This is intentionally framed as a supplement to broader CultureBotAI onboarding materials, not a replacement for them.
Why this belongs in this repo
The broader ecosystem already has onboarding and best-practices material, but this repo still has local gaps that matter for day-to-day contributor workflow:
pyproject.tomlsrc/process_terms/auto_terms_table.pyThat means a contributor can be onboarded into the larger CultureBotAI environment and still not have enough repo-specific guidance to work productively here.
What this guide emphasizes
1. Why the Codex CLI is especially useful here
The guide explicitly argues for the CLI as the best starting point for this repo because it:
It also contrasts that with the web interface, desktop app, and IDE plugins so contributors understand the tradeoffs.
2. Why repo setup is a collaboration issue, not just a convenience issue
The guide also emphasizes that repo setup is for:
That framing is important here because undergraduates often optimize for getting something to run once, while the repo needs workflows that are repeatable and legible to other people.
Contents added
The guide covers:
@lbl.govaddress and actually being provisioned in the workspaceCloses #7.