From fb705b9497bb58a2a282e60fd6db2659327137ec Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 16 Aug 2026 04:20:53 +0000 Subject: [PATCH 1/2] Add a walkthrough and shortcuts for non-technical contributors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Everything written so far assumed the reader knew what a branch was. Someone who just wants Jane Doe on the mentors page had nowhere to start. GUIDE.md starts from having no accounts at all: sign up for GitHub, get added to the org, get Claude access, then a worked example of adding a mentor from first message to published. It names the things people will actually hit — the missing Merge button is deliberate rather than broken, preview pages carry a badge so they are not mistaken for the live site, changes can be iterated on before anyone sees them — and ends with a glossary so the GitHub vocabulary is decodable rather than a wall. Four skills in .claude/skills/ turn the common jobs into /add-mentor, /add-sponsor, /update-events and /new-season. They prompt for exactly what each task needs, and encode the mistakes already made once: event codes that must match their venue after North Charleston was linked to the Pembroke event, sponsor logo dimensions that must be read off the file rather than guessed, season results that must come from The Blue Alliance rather than last year's block. Claude can also load them from plain English, so nobody has to memorise a command. For anyone who will not use Claude, an issue form collects the same information in a plain web form for a maintainer to action, with blank issues turned off so the form is the path of least resistance. Each skill ends by pointing back at "Handing work back" in CLAUDE.md, so a change made through a shortcut still arrives with screenshots and a preview. --- .claude/skills/add-mentor/SKILL.md | 86 +++++++++ .claude/skills/add-sponsor/SKILL.md | 69 ++++++++ .claude/skills/new-season/SKILL.md | 77 ++++++++ .claude/skills/update-events/SKILL.md | 70 ++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/website-change.yml | 69 ++++++++ CLAUDE.md | 8 + CONTRIBUTING.md | 13 +- GUIDE.md | 203 ++++++++++++++++++++++ README.md | 9 +- 10 files changed, 607 insertions(+), 5 deletions(-) create mode 100644 .claude/skills/add-mentor/SKILL.md create mode 100644 .claude/skills/add-sponsor/SKILL.md create mode 100644 .claude/skills/new-season/SKILL.md create mode 100644 .claude/skills/update-events/SKILL.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/website-change.yml create mode 100644 GUIDE.md diff --git a/.claude/skills/add-mentor/SKILL.md b/.claude/skills/add-mentor/SKILL.md new file mode 100644 index 0000000..33172f4 --- /dev/null +++ b/.claude/skills/add-mentor/SKILL.md @@ -0,0 +1,86 @@ +--- +name: add-mentor +description: Add, update or remove a mentor on the LYNK Robotics mentors page. Use when someone wants to put a new mentor on the website, change a mentor's role or blurb, or take a mentor down. +argument-hint: "[mentor name, if you know it]" +--- + +# Add or update a mentor + +The person asking may not know how the site is built. Do not make them learn. +Ask for what you need in plain language, one short round of questions, then do +the whole job. + +## What you need + +Everything lives in `src/_data/mentors.json`. Each mentor is one object: + +```json +{ + "name": "Jane Doe", + "photo": "/assets/img/mentors/jane-doe.jpg", + "title": "Mechanical Engineer @ Acme", + "role": "Design Mentor", + "why": "I mentor because ...", + "since": "2026-Present", + "alum": "FRC Alum" +} +``` + +- **name** — as they want it shown. Nicknames go in quotes, matching the + existing entries: `Daniel "Danny" Smith`. +- **title** — their day job, written `Role @ Employer`. +- **role** — what they do on the team, e.g. `Design Mentor`, + `Scouting and Strategy`. +- **why** — their "My whY" sentence. Ask for it in their own words; the page + prints it after a bold `My whY:` label, so do not repeat that label in the text. +- **since** — `2026-Present` for someone joining now. +- **alum** — `FRC Alum`, `FLL + FRC Alum`, or `""` if neither. Optional. + +## Ask for these + +If the request did not already include them, ask for all of it in one message +rather than one question at a time: + +1. Full name, as it should appear +2. Day job (role and employer) +3. Their role on the team +4. Their "My whY" sentence +5. Are they an FRC or FLL alum? +6. A photo + +## The photo + +Mentor photos are square, about 500×500, JPEG quality ~82, saved as +`src/assets/img/mentors/.jpg` (all lowercase, hyphenated). + +- If they attach or point to a file, resize and convert it yourself. Crop to a + square centred on the face rather than squashing it. +- If they have no photo yet, say so and offer to add the mentor without one — + but note the card will look unfinished, so a photo is worth chasing. +- Nothing in the build resizes images. Getting this right here is the only + chance. + +## Removing a mentor + +Delete their object from `mentors.json` and delete their photo file. Do not +leave an orphan image. + +## Ordering + +`mentors.json` is rendered in file order, which is roughly lead coaches first, +then alphabetical by surname. Put a new mentor where they belong in that +pattern rather than appending to the end. + +## Finish the job + +Follow "Handing work back" in CLAUDE.md: + +1. `npm run check` +2. `npm run review -- review.html --pages=/our-people/mentors/` +3. Publish `review.html` as an artifact, link it in your reply +4. Push a branch, open a pull request, and tell them a maintainer has to merge + it before it goes live + +In your reply, show them the mentor card as it will appear and say plainly what +happens next. Avoid Git vocabulary — "I have put this up for one of the +maintainers to approve" beats "I opened a PR against main". diff --git a/.claude/skills/add-sponsor/SKILL.md b/.claude/skills/add-sponsor/SKILL.md new file mode 100644 index 0000000..d945b22 --- /dev/null +++ b/.claude/skills/add-sponsor/SKILL.md @@ -0,0 +1,69 @@ +--- +name: add-sponsor +description: Add, move or remove a sponsor (investor) logo on the LYNK Robotics site. Use when a new business or family starts supporting the team, when a sponsor moves up a tier, or when one should come off. +argument-hint: "[sponsor name, if you know it]" +--- + +# Add or update a sponsor + +The investor wall appears on the home page and on each season page, all from +one file: `src/_data/sponsors.json`. Editing it updates every page at once. + +## Tiers + +Tiers render top to bottom, largest logos first. They mirror the giving levels +on the Invest page: + +| Tier in the file | Giving level | Logo size | +| --- | --- | --- | +| `Peak` | $15,000+ | `xl` | +| `Overlook` | $5,000–$15,000 | `lg` | +| `Trailhead` | $1,000–$5,000 | `md` | +| `Gorge` | up to $1,000 | `md` | +| `Supporters` | everyone else | `md` | + +If you are told an amount but not a tier, work the tier out from the table and +say which one you picked, so it can be corrected. + +## The entry + +```json +{ + "name": "Acme Manufacturing", + "logo": "/assets/img/sponsors/acme-manufacturing.png", + "width": 540, + "height": 210 +} +``` + +- **width / height** are the logo's real pixel dimensions. They stop the page + reflowing as logos load, so they must be accurate — read them off the file + you saved, do not guess. +- **`"logo": null`** renders the sponsor as their name in text instead. Use it + when there is no logo, as with `Moore Family`. +- **`"showName": true`** prints the name underneath a logo. Use it only when + the logo alone does not say who they are, as with Thomas Jefferson Classical + Academy. + +## The logo file + +Save to `src/assets/img/sponsors/.png`, 540–700px wide. + +- **PNG** if it needs transparency — most logos do. +- **JPEG** if it is a photographic or full-bleed logo with no transparency. +- Trim surrounding whitespace so logos in a row look optically similar in size. +- A logo on a white rectangle will show as a white box on the page. Ask for a + transparent version if that is what you were given. + +## Finish the job + +Follow "Handing work back" in CLAUDE.md: + +1. `npm run check` +2. `npm run review -- review.html --pages=/,/seasons/2025/` — the wall appears + on both, and a mis-sized logo shows up in the row spacing +3. Publish `review.html` as an artifact and link it in your reply +4. Push a branch, open a pull request, and say a maintainer has to merge it + +Check the screenshot before handing back: a logo that dwarfs its row, or +vanishes into the background, is the usual mistake and it is obvious on sight. diff --git a/.claude/skills/new-season/SKILL.md b/.claude/skills/new-season/SKILL.md new file mode 100644 index 0000000..df534ca --- /dev/null +++ b/.claude/skills/new-season/SKILL.md @@ -0,0 +1,77 @@ +--- +name: new-season +description: Create the season page for a new competition year on the LYNK Robotics site, or fill in results for the current one. Use at the start of a season, or after events when records, awards, robot details or the roster need updating. +argument-hint: "[year, e.g. 2026]" +--- + +# Add or update a season page + +`/seasons//` is generated from one entry in `src/_data/seasons.json`. +There is no page template to create — add the entry and the page exists. + +## Results must come from The Blue Alliance + +**Never copy last year's block and edit the numbers, and never invent a +result.** The 2025 page originally shipped with 2024 records and links to 2024 +events, because someone did exactly that. + +The authoritative record is `https://www.thebluealliance.com/team/9496/`. +It is server-rendered, so it can be read directly without an API key. Take: + +- the official and overall record from the "Event Results" line +- each event's rank, record, awards and playoff outcome from its own block +- the event URL from that block — `https://www.thebluealliance.com/event/` + +If TBA states no playoff outcome for an event, leave `playoff` as `""`. The +template omits the line. Do not fill the gap with a guess. + +## The entry + +Copy the shape from an existing season, then replace every value: + +- `year`, `name`, `robotName`, `game`, `gameVideo`, `gameSummary` +- `heroImage`, `robotImage`, `bannersImage`, `gameLogo` +- `buildLog` — `url`, `label` and an optional `note` +- `tba` — the team page for that year +- `summary` — the paragraph above the banners +- `robot` — `specs`, `record`, `capabilities[]` +- `eventsRecord` and `events[]` +- `roster[]` +- `gallery` — `{ "dir": "...", "count": N }` +- `sponsorsHeading` and `divider` — optional, both may be `null` + +Put the newest season first in the file. + +## Images + +Into `src/assets/img/`, resized before committing — nothing in the build +resizes: + +| What | Where | Size | +| --- | --- | --- | +| Hero | `hero/season-.jpg` | 1400px wide | +| Robot | `hero/season--robot.jpg` | 1800px wide | +| Game logo | `seasons//-logo.png` | 900px, transparent | +| Banners | `seasons//banners.jpg` | 1400px wide | +| Gallery | `seasons//gallery/01.jpg`, `02.jpg`, … | 1400px wide | + +Gallery files must be numbered from `01` with no gaps, and `gallery.count` must +match how many there are — the template counts up to it, so a mismatch shows as +a broken image. + +## Add it to the menu + +A new season does not appear in the navigation on its own. Add it to the +`Seasons` dropdown in `src/_data/site.json`, newest first. + +## Finish the job + +Follow "Handing work back" in CLAUDE.md: + +1. `npm run check` +2. `npm run review -- review.html --pages=/seasons//` +3. Publish `review.html` as an artifact and link it in your reply +4. Push a branch, open a pull request, and say a maintainer has to merge it + +In your reply, list each event with its record and awards, and say you took +them from The Blue Alliance, so the numbers can be spot-checked. diff --git a/.claude/skills/update-events/SKILL.md b/.claude/skills/update-events/SKILL.md new file mode 100644 index 0000000..2ff9da5 --- /dev/null +++ b/.claude/skills/update-events/SKILL.md @@ -0,0 +1,70 @@ +--- +name: update-events +description: Update the upcoming events, competition dates or meeting times on the LYNK Robotics home page. Use when a competition is added, moved or cancelled, when the team qualifies for States or Worlds, or when meeting times change. +--- + +# Update the home page events + +Everything is in `src/_data/events.json`. Nothing else needs touching. + +## Meeting times + +```json +"meetings": { + "when": "Mon, Tues, Thurs, & Fri | 6:30-9 PM + Sat | 11:30 AM", + "what": "Season Team Meetings", + "where": "9496 LYNK Robotics HQ, 228 Callahan Koon Rd, Spindale, NC" +} +``` + +Free text — write it the way the team says it out loud. + +## Competitions + +```json +{ + "start": "2026-03-05", + "end": "2026-03-07", + "kind": "District Competition", + "venue": "Heritage High School | Wake Forest, NC", + "url": "https://frc-events.firstinspires.org/2026/NCWK2", + "city": "Wake Forest, NC", + "conditional": true +} +``` + +- **start / end** are ISO dates. The page formats them as "March 5 - March 7", + so never hand-write the display text. +- **venue** is `Venue name | City, ST`. Get the state right — North Charleston + is **SC**, not NC. That exact error was live on the old site for a season. +- **url** is the FIRST event page. The code is the last path segment, e.g. + `SCCHA` for South Carolina Charleston, `NCPEM` for Pembroke. **Check the code + matches the venue** — the old site had two of them swapped. +- **city** is used on the Invest page, where only the city is shown. +- **conditional: true** means "if we qualify". The first conditional event in + the list is automatically preceded by the "Additional competition dates we'll + attend, if we're able to qualify" note, so ordering matters: keep confirmed + events first, conditional ones after. + +## Qualifying + +When the team qualifies for States or Worlds, drop `"conditional": true` from +that event. It moves above the note by itself. Do not rewrite the note. + +## Verifying an event + +Event codes and dates are on . If you +have network access, fetch the URL and confirm it resolves to the right event +before saving it. A wrong link is invisible in a screenshot. + +## Finish the job + +Follow "Handing work back" in CLAUDE.md: + +1. `npm run check` +2. `npm run review -- review.html --pages=/,/invest/` — events show on both +3. Publish `review.html` as an artifact and link it in your reply +4. Push a branch, open a pull request, and say a maintainer has to merge it + +In your reply, list the dates as they will appear on the page so they can be +checked at a glance. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..247af03 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: How to change the website yourself + url: https://github.com/LynkRobotics/website/blob/main/GUIDE.md + about: A five-minute walkthrough. No technical knowledge needed. + - name: Email the team + url: mailto:info@lynkrobotics.org + about: For anything that is not a website change. diff --git a/.github/ISSUE_TEMPLATE/website-change.yml b/.github/ISSUE_TEMPLATE/website-change.yml new file mode 100644 index 0000000..14abd6d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/website-change.yml @@ -0,0 +1,69 @@ +name: Request a website change +description: Ask for something on lynkrobotics.org to be added, changed or removed. No technical knowledge needed. +title: "Website: " +labels: ["website request"] +body: + - type: markdown + attributes: + value: | + Fill this in and a maintainer will take it from there. You do not need + to know how the website is built. + + **In a hurry, or want to see it yourself first?** You can make the + change directly by asking Claude — it takes about five minutes and no + technical knowledge. See the + [walkthrough](https://github.com/LynkRobotics/website/blob/main/GUIDE.md). + + - type: dropdown + id: kind + attributes: + label: What kind of change is this? + options: + - Add or update a mentor + - Add or update a sponsor / investor + - Competition dates or meeting times + - Fix wording or a typo + - Add or replace photos + - Season page (results, roster, robot) + - Something else + validations: + required: true + + - type: input + id: page + attributes: + label: Which page? + description: A link, or just the name of the page. Write "not sure" if you do not know. + placeholder: https://www.lynkrobotics.org/our-people/mentors/ + validations: + required: true + + - type: textarea + id: change + attributes: + label: What should change? + description: | + Describe it the way you would say it out loud. If you are replacing + words, give the exact new wording. Attach photos by dragging them into + this box. + placeholder: | + Add Jane Doe to the mentors page. She is a Mechanical Engineer at Acme + and is our Design Mentor. Her "My whY" is: "I mentor because ..." + Photo attached. She joined this season and is an FRC alum. + validations: + required: true + + - type: input + id: deadline + attributes: + label: Is it needed by a particular date? + description: Optional. Say so if it is tied to a competition or an event. + placeholder: Before the Wake Forest event on March 20 + + - type: checkboxes + id: confirm + attributes: + label: Before submitting + options: + - label: I have checked the details above are correct (names, spellings, dates) + required: true diff --git a/CLAUDE.md b/CLAUDE.md index f53a7f2..37bcc1c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,6 +42,7 @@ src/ *.njk one file per page seasons/season.njk generates /seasons// for every entry in seasons.json redirect.njk generates a stub for every entry in redirects.json +.claude/skills/ /add-mentor, /add-sponsor, /update-events, /new-season scripts/check-links.mjs fails the build on a broken internal link scripts/mark-preview.mjs turns a build into a badged, noindexed preview scripts/review-shots.mjs screenshots the site into a single review page @@ -107,6 +108,13 @@ present in Claude Code environments. ## Adding things +Four project skills in `.claude/skills/` cover the common jobs and encode the +gotchas — event codes matching venues, sponsor logo dimensions, season results +coming from The Blue Alliance. Use them when a request matches, rather than +working from the notes below. Most people asking are not technical: see +GUIDE.md for the vocabulary they will use and expect back. + + **A mentor:** add an object to `src/_data/mentors.json` and put a square photo in `src/assets/img/mentors/.jpg` (about 500×500, JPEG quality ~82). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5120a84..bdd31d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,10 @@ group of maintainers approves and publishes it.** Nothing you do can put something on the live site by accident. +> **Not technical?** Read **[GUIDE.md](GUIDE.md)** instead. It covers the same +> ground without assuming you know what Git is, and starts from having no +> accounts at all. This page is the shorter, more technical version. + ``` anyone in the org website maintainers ───────────────── ─────────────────── @@ -19,7 +23,9 @@ something on the live site by accident. You do not need to know Git, Eleventy, or HTML. 1. Open the repository in [Claude Code](https://claude.ai/code). -2. Describe the change in plain language: +2. Describe the change in plain language, or use one of the shortcuts the + repository provides — `/add-mentor`, `/add-sponsor`, `/update-events`, + `/new-season` — which prompt you for exactly what each task needs: > Add Jane Doe to the mentors page — Mechanical Mentor, engineer at Acme, > joined 2026. Her photo is attached. @@ -69,6 +75,11 @@ few lines of JSON, not HTML. You will not see a Merge button, and that is expected — merging is restricted to maintainers. +## Not using Claude at all + +Open a request and a maintainer will handle it: + + ## Becoming a maintainer Maintainers are members of the diff --git a/GUIDE.md b/GUIDE.md new file mode 100644 index 0000000..7381796 --- /dev/null +++ b/GUIDE.md @@ -0,0 +1,203 @@ +# How to change the LYNK website + +You do not need to know how to code. You do not need to understand GitHub. You +describe the change in ordinary English, look at a picture of the result, and a +maintainer publishes it. + +Most changes take about five minutes. + +--- + +## What you can change + +Anything you can see: mentors, sponsors, competition dates, wording, photos, +season results, FAQ answers. + +**You cannot break the live site.** Nothing you do goes public on its own. Every +change waits for one of the maintainers to approve it, and if something wrong +slips through it can be undone in seconds. + +--- + +## Part 1 — One-time setup + +You do this once, ever. About ten minutes. + +### 1. Get a GitHub account + +GitHub is where the website's files live. Think of it as the filing cabinet. + +Sign up at **** — it is free. Use whatever email you +like and pick any username. + +### 2. Get added to the team + +Send your GitHub username to ****, or tell a maintainer +directly. They will send you an invitation to the LynkRobotics organisation. + +Accept it from the email, or at ****. + +> Until you accept, you will not be able to make changes. If you are not sure +> whether it worked, open — if you can +> see the files, you are in. + +### 3. Get access to Claude + +Claude is the assistant that actually makes the edits. Go to +**** and sign in or sign up. + +Ask a maintainer whether the team has a plan you should be added to. Making +changes this way needs Claude Code, which is on the paid plans. + +**That is the setup finished.** You never have to do it again. + +--- + +## Part 2 — Making your first change + +Let us walk through a real one: adding a mentor. + +### Step 1 — Open the website project + +Go to ****. + +Choose the **LynkRobotics/website** repository from the list. If it is not +there, look for an option to connect GitHub and grant access, then try again. + +You will get a chat box. That is the whole interface. + +### Step 2 — Say what you want + +Type it the way you would say it to a person: + +> Add Jane Doe to the mentors page. She is a Mechanical Engineer at Acme and +> she is our Design Mentor. Her "My whY" is: "I mentor because watching a +> student solve a problem they thought was beyond them never gets old." She +> joined this season and she is an FRC alum. + +Then drag her photo into the chat. + +**Do not worry about getting it perfectly right.** If something is missing, +Claude will ask. If you would rather be prompted through it, type `/add-mentor` +and it will ask you for each piece. + +### Step 3 — Wait a minute + +Claude will edit the files, check nothing is broken, and put the change forward +for approval. You do not need to follow along. + +### Step 4 — Look at the result + +Claude's reply will contain a **link to pictures** of the pages you changed, at +both computer and phone size. Click it and check it looks right. + +You will also get a link to the **pull request** — that is GitHub's word for +"a change waiting to be approved". On that page, a minute or so later, a comment +appears with a **preview link**. That is the real website with your change in +it, which you can click around exactly like the live site. + +> Preview pages have a small orange **Preview** badge in the corner. That is how +> you know you are not looking at the live site. + +### Step 5 — Ask for changes, if you want any + +Go back to the chat and say so: + +> Her photo is a bit tight, can you crop it wider? + +> Actually her title should be Senior Mechanical Engineer. + +Claude updates the same request and sends new pictures. Repeat as many times as +you like — nothing is public yet. + +### Step 6 — Ask a maintainer to publish it + +Send the pull request link to a maintainer, or comment on the page tagging one. + +They check it and press Merge. **Your change is live within about two minutes.** + +> You will not have a Merge button yourself. That is deliberate, not a mistake — +> only maintainers can publish. + +--- + +## Part 3 — Things people ask for most + +Type any of these straight into the chat. The `/` shortcuts prompt you through +each step, but plain English works just as well. + +| What you want | Say this | +| --- | --- | +| Add or update a mentor | `/add-mentor` or *"Add Jane Doe to the mentors page…"* | +| Add a sponsor | `/add-sponsor` or *"Acme is a new sponsor at the $5,000 level, logo attached"* | +| Change competition dates | `/update-events` or *"The Pembroke event moved to March 28–29"* | +| We qualified for States | `/update-events` or *"We qualified for States, take the 'if we qualify' note off it"* | +| A new season page | `/new-season 2027` | +| Fix a typo | *"On the FAQs page, 'recieve' should be 'receive'"* | +| Replace a photo | *"Replace the photo on the home page with this one"* — then drag it in | +| Update the roster | *"Add these students to the 2026 roster: …"* | + +### Photos + +Just drag them into the chat. Claude resizes and crops them. + +Send the **biggest version you have** — a photo can be made smaller without +losing quality, but not larger. Straight off a phone or camera is ideal. + +--- + +## Part 4 — If you would rather not use Claude + +Open a request instead and a maintainer will do it: + +**** + +Choose *Request a website change*, fill in the form, attach any photos. That is +all. + +--- + +## If something goes wrong + +**"I do not see the repository in Claude."** +You are probably not in the organisation yet, or have not accepted the +invitation. Check loads for you. + +**"Claude says a check failed."** +Something in the change does not build. Say *"that check failed, can you fix +it?"* — it can read the error and sort it out. + +**"The preview link does not work yet."** +It takes a minute or two to build. Refresh the pull request page. + +**"I published something wrong."** +Tell a maintainer straight away. Any change can be undone in about a minute — +nothing is ever lost. + +**"Claude changed more than I asked for."** +Say so: *"only change the mentors page, put the rest back."* + +--- + +## The words GitHub uses + +You can ignore all of these, but in case you see them: + +| Word | What it means here | +| --- | --- | +| **Repository** (repo) | The folder holding the website's files | +| **Branch** | A private copy of the site where your change lives until it is approved | +| **Commit** | One saved edit | +| **Pull request** (PR) | A change waiting for approval | +| **Merge** | Approving it — this is what makes it live | +| **Main** | The version that is live right now | + +--- + +## Who to ask + +- Website not doing what you expect → +- Need publishing rights → ask a member of the + [website-maintainers](https://github.com/orgs/LynkRobotics/teams/website-maintainers) + team +- Curious how it all works → [README.md](README.md) and [SETUP.md](SETUP.md) diff --git a/README.md b/README.md index ea9f523..401ad37 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,12 @@ operating under Inspire Carolina, Inc. Static site built with [Eleventy](https://www.11ty.dev/), published to GitHub Pages at . -> **Want to change something?** [CONTRIBUTING.md](CONTRIBUTING.md) is the -> short version — you do not need to know Git or HTML. +> **Want to change something on the site?** Start with +> **[GUIDE.md](GUIDE.md)** — a walkthrough from nothing to a published change. +> No technical knowledge needed. > -> **Setting up hosting or permissions?** [SETUP.md](SETUP.md) records how the -> domain, deploys and merge rules are configured. +> **Working on the code?** [CONTRIBUTING.md](CONTRIBUTING.md). +> **Hosting and permissions?** [SETUP.md](SETUP.md). --- From f2a68bc719a0a059bde37077e476da27ab858bae Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 16 Aug 2026 04:38:03 +0000 Subject: [PATCH 2/2] Make the contributor guide account- and browser-only Team mentors hand out the Claude account, so the guide no longer sends people off to work out plans for themselves. Setup gains a step for connecting GitHub and granting access to LynkRobotics/website, which is what lets Claude push a branch and open a pull request, and says plainly that approving it does not let Claude publish. Nothing on the non-technical path now mentions a terminal: the local npm instructions move out of README's everyday workflow into a section marked for developers, and CONTRIBUTING labels its manual route the same way. GitHub access questions go to github@lynkrobotics.org. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01JwRVGEYx7WxaNm8yvxSrUZ --- CONTRIBUTING.md | 5 ++-- GUIDE.md | 68 +++++++++++++++++++++++++++++++++++++++---------- README.md | 25 +++++++++--------- 3 files changed, 71 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bdd31d8..9584999 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,9 +39,10 @@ You do not need to know Git, Eleventy, or HTML. `CLAUDE.md` in this repository tells Claude where every piece of content lives and what the house style is, so you do not have to. -## The manual way +## The manual way (developers only) -If you would rather edit directly: +Entirely optional — nothing in the workflow above needs it. If you would rather +edit directly: ```bash git clone https://github.com/LynkRobotics/website.git diff --git a/GUIDE.md b/GUIDE.md index 7381796..3cd1ff3 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -4,6 +4,9 @@ You do not need to know how to code. You do not need to understand GitHub. You describe the change in ordinary English, look at a picture of the result, and a maintainer publishes it. +Everything happens in a web browser. **There is nothing to install and nothing +to run on your computer.** + Most changes take about five minutes. --- @@ -32,8 +35,8 @@ like and pick any username. ### 2. Get added to the team -Send your GitHub username to ****, or tell a maintainer -directly. They will send you an invitation to the LynkRobotics organisation. +Send your GitHub username to ****, or speak to a team +mentor. They will send you an invitation to the LynkRobotics organisation. Accept it from the email, or at ****. @@ -43,11 +46,35 @@ Accept it from the email, or at ****. ### 3. Get access to Claude -Claude is the assistant that actually makes the edits. Go to -**** and sign in or sign up. +Claude is the assistant that actually makes the edits. + +**Ask a team mentor for access to Claude.** The team provides the account, so +there is nothing for you to buy and nothing to install. + +Once you have the login, go to **** and sign in with it. + +### 4. Let Claude see the website files + +The one fiddly step, and it is also once-only. + +Go to ****, signed in with that same account. This is +the part of Claude that can work on files — an ordinary chat window at +claude.ai cannot. -Ask a maintainer whether the team has a plan you should be added to. Making -changes this way needs Claude Code, which is on the paid plans. +You will be asked to connect GitHub. Click through it, and when GitHub asks +which repositories Claude may use, choose **LynkRobotics/website**. + +Approving that is what lets Claude do the two things this whole guide depends +on: save your change onto a branch of its own, and open a pull request asking a +maintainer to approve it. It does **not** let Claude publish — only a maintainer +pressing Merge can do that. + +> **If GitHub says an organisation owner has to approve it,** click the button +> to send the request, then email so somebody says yes. +> This only ever happens once. + +You are done when **LynkRobotics/website** appears in the list of projects at +. **That is the setup finished.** You never have to do it again. @@ -59,12 +86,13 @@ Let us walk through a real one: adding a mentor. ### Step 1 — Open the website project -Go to ****. +Go to **** and choose **LynkRobotics/website** from the +list of projects. If it is not there, go back to setup step 4. -Choose the **LynkRobotics/website** repository from the list. If it is not -there, look for an option to connect GitHub and grant access, then try again. +If it asks which branch to start from, choose **main**. -You will get a chat box. That is the whole interface. +You get a chat box. That is the whole interface — nothing to install, nothing to +type into a terminal, nothing to run on your own computer. ### Step 2 — Say what you want @@ -84,7 +112,11 @@ and it will ask you for each piece. ### Step 3 — Wait a minute Claude will edit the files, check nothing is broken, and put the change forward -for approval. You do not need to follow along. +for approval. You do not need to follow along, and you do not need to press +anything to save it. + +> If it finishes without giving you a link to a pull request, just say **"please +> open a pull request for this"**. ### Step 4 — Look at the result @@ -160,8 +192,15 @@ all. ## If something goes wrong **"I do not see the repository in Claude."** -You are probably not in the organisation yet, or have not accepted the -invitation. Check loads for you. +Three things to check, in order. Are you at rather than +ordinary claude.ai? Does load when you +are signed in to GitHub — if not, your invitation is still waiting. And did you +tick **LynkRobotics/website** when Claude asked which repositories it may use? +Setup step 4 covers redoing that. Still stuck: . + +**"It says an organisation owner needs to approve."** +Send the request from that screen, then email . Once +somebody approves it you will not be asked again. **"Claude says a check failed."** Something in the change does not build. Say *"that check failed, can you fix @@ -196,6 +235,9 @@ You can ignore all of these, but in case you see them: ## Who to ask +- Getting into GitHub, or Claude cannot see the repository → + , or any team mentor +- Access to Claude → ask a team mentor - Website not doing what you expect → - Need publishing rights → ask a member of the [website-maintainers](https://github.com/orgs/LynkRobotics/teams/website-maintainers) diff --git a/README.md b/README.md index 401ad37..75f7ea1 100644 --- a/README.md +++ b/README.md @@ -82,17 +82,6 @@ the `website-maintainers` team. To roll back, revert the merge commit on `main` — the next deploy restores the previous state. -### If you do want to run it locally - -Never required, but it is the fastest loop if you are editing yourself: - -```bash -git clone https://github.com/LynkRobotics/website.git -cd website -npm install -npm start # http://localhost:8080, live reload -``` - --- ## What lives where @@ -116,7 +105,19 @@ Content is **data, not markup**. Most changes are a few lines of JSON. Page templates are the `.njk` files in `src/`. The shared header and footer are in `src/_includes/`. -## Commands +## Running it locally + +**Only for people editing the code themselves.** The workflow above never needs +it — see [GUIDE.md](GUIDE.md) for the browser-only path. + +```bash +git clone https://github.com/LynkRobotics/website.git +cd website +npm install +npm start # http://localhost:8080, live reload +``` + +### Commands | Command | What it does | | --------------- | --------------------------------------------------------- |