From 0823dfefb869a3960a58bd341a3468b611f2bb9a Mon Sep 17 00:00:00 2001 From: Adnaan Badr Date: Sat, 15 Aug 2026 17:15:13 +0000 Subject: [PATCH] docs(contributing): the examples repo is archived; make its page say so MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /contributing/examples described how to contribute to livetemplate/examples. GitHub has that repository archived and read-only, so the workflow it documented cannot be followed: it told the reader to create a directory there, write a go.mod pinning livetemplate v0.1.0 (core is at v0.25.0), and add a README in the register that #137 spent a PR removing from the ten pages that copied it. Two things turned out to be true that were not obvious. The page was never actually mirrored. It carries source_repo front matter pointing at the archived repo, but /contributing/examples has no entry in source-of-truth.yaml, and cmd/sync only walks entries from that file (sync.go Run -> filterByRepo over cfg.Pages; nothing scans front matter). So it was already docs-native and merely mislabelled, and correcting the front matter changes no sync behaviour. source-of-truth.md and CLAUDE.md both claimed otherwise. Both now say the page is docs-native and why, so the next person does not skip it as unfixable. The page itself now says the repo is archived, points at this repo's CONTRIBUTING.md for the current steps, and repeats the two rules that have already cost real work here: include code rather than retyping it, and read VOICE.md first. Verified: voice-check green — it failed twice on this page first, once for quoting a banned phrase as an example of what not to write, and once for three passives I had written, so both got fixed rather than the ceiling raised. tinkerdown validate 98/98, e2e green, and the page read back in a real browser with all six of its links resolving. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_0166MK1arBYbVZq6wfm8EsQZ --- CLAUDE.md | 2 + content/_meta/source-of-truth.md | 2 +- content/contributing/examples.md | 237 ++++--------------------------- 3 files changed, 33 insertions(+), 208 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e4436d9..52bbf1d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,6 +19,8 @@ Editing it here is work that gets thrown away. Fix it in the source repo. - Mirrored: `content/reference/*`, `content/changelog/*`, `content/guides/*` (except `index.md`), `content/cli/*`, `content/client/*`, `content/contributing/*` + **except `contributing/examples.md`** — livetemplate/examples is archived, so + that page is docs-native - Docs-native: `content/index.md`, `content/getting-started/*`, `content/recipes/**` (including `recipes/apps/*`), the section `index.md` files diff --git a/content/_meta/source-of-truth.md b/content/_meta/source-of-truth.md index e633e67..b1ae165 100644 --- a/content/_meta/source-of-truth.md +++ b/content/_meta/source-of-truth.md @@ -139,7 +139,7 @@ headings, emoji, exclamation marks — while the rest of the site moved on. See | livetemplate contrib | `livetemplate` | `CONTRIBUTING.md` | `/contributing/livetemplate` | yes | | client contrib | `client` | `CONTRIBUTING.md` | `/contributing/client` | yes | | lvt contrib | `lvt` | `CONTRIBUTING.md` | `/contributing/cli` | yes | -| examples contrib | `examples` | `CONTRIBUTING.md` | `/contributing/examples` | yes | +| examples contrib | this repo | `content/contributing/examples.md` | `/contributing/examples` | no | ### Changelog (manually concatenated) diff --git a/content/contributing/examples.md b/content/contributing/examples.md index 66b7139..487bf1d 100644 --- a/content/contributing/examples.md +++ b/content/contributing/examples.md @@ -1,219 +1,42 @@ --- title: "Contributing to examples" -source_repo: "https://github.com/livetemplate/examples" -source_path: "CONTRIBUTING.md" -source_commit: "1abf1351852266a0bd3c3b62363593a2393d22cd" +source_repo: "https://github.com/livetemplate/docs" +source_path: "content/contributing/examples.md" --- -# Contributing to LiveTemplate Examples +# Contributing to examples -Thank you for your interest in contributing examples! +Examples used to live in `livetemplate/examples`. **GitHub has that repository +archived, so it is read-only.** Nothing there accepts contributions any more, +and the instructions this page used to carry described a workflow that no +longer exists. -## Adding a New Example +Every runnable app now lives in this repository, under `examples//`, next +to the page that documents it. You edit the two together, so a change to one +turns up in review beside the other. -### 1. Create Example Directory +## Where to start -```bash -mkdir my-example -cd my-example -``` +[`CONTRIBUTING.md`](https://github.com/livetemplate/docs/blob/main/CONTRIBUTING.md) +in the docs repo has the current steps — the four files an example needs, how to +mount it in `cmd/site`, and how to run its chromedp test. -### 2. Create go.mod +Two rules from it are worth repeating here, because getting either wrong has +already cost real work: -```go -module my-example +- **Include code, don't retype it.** Cite the app with + `` ```go include="/examples/foo/foo.go" lines="5-15" ``. A pasted snippet + drifts the moment either side changes and nothing catches it. The chat recipe + documented a `Change(ctx *ActionContext)` API that never existed, for as long + as it was hand-written. +- **Read [`VOICE.md`](https://github.com/livetemplate/docs/blob/main/VOICE.md) + before writing the prose.** The ten pages under + [Apps](/recipes/apps/) came from example READMEs and kept that register — + Title Case headings, emoji, exclamation marks — until a later pass took it + back out. -go 1.25 +## Contributing to the libraries -require github.com/livetemplate/livetemplate v0.1.0 - -// If using E2E tests: -// require github.com/livetemplate/lvt v0.1.0 -``` - -### 3. Write Example Code - -```go -package main - -import ( - "log" - "net/http" - - lt "github.com/livetemplate/livetemplate" -) - -func main() { - // Your example code -} -``` - -### 4. Add README.md - -Create `my-example/README.md` explaining: -- What the example demonstrates -- How to run it -- Key features -- Any prerequisites - -### 5. Add E2E Tests (Recommended) - -Use Chromedp for browser-based E2E tests: - -```go -package main - -import ( - "testing" - - lvttest "github.com/livetemplate/lvt/testing" -) - -func TestMyExample(t *testing.T) { - // Your E2E test -} -``` - -### 6. Update Main README - -Add your example to the main `README.md` with: -- Example name and description -- Directory path -- How to run -- Key features - -## Example Guidelines - -### Code Quality - -- Follow Go best practices -- Add comments for complex logic -- Handle errors properly -- Use meaningful variable names - -### Documentation - -- Clear README in example directory -- Code comments explaining key concepts -- Step-by-step setup instructions - -### Testing - -- Add E2E tests using Chromedp -- Test happy paths and edge cases -- Verify UI updates correctly -- Test WebSocket communication - -### Client Library - -- Use CDN version for production examples -- Reference client library version in comments -- Show both CDN and local dev setup - -### Dependencies - -- Minimize external dependencies -- Use standard library when possible -- Document any required dependencies - -## Local Development with Core Library - -If you need to test your example against unreleased core library or LVT changes, you have two options: - -### Recommended: Go Workspace (Automatic) - -The **easiest way** - Go automatically uses local modules without any `go.mod` changes: - -```bash -# From parent directory containing all repos -cd .. -./setup-workspace.sh - -# Now test examples with local core library and LVT -cd examples -./test-all.sh # Uses local livetemplate + lvt - -# Or test individual example -cd counter -go test -v # Automatically uses ../livetemplate and ../lvt -``` - -The workspace setup is done once and affects all repositories. See the [core library CONTRIBUTING.md](https://github.com/livetemplate/livetemplate/blob/main/CONTRIBUTING.md#testing-core-changes-with-lvtexamples) for details. - -### Alternative: Manual Replace Directives - -If you prefer manual control: - -```bash -# Enable local development mode for all examples -./scripts/setup-local-dev.sh - -# Test with local libraries -./test-all.sh - -# Revert to published versions -./scripts/setup-local-dev.sh --undo -``` - -**Directory structure for both methods:** -``` -parent/ -├── livetemplate/ (core library) -├── lvt/ (CLI tool) -└── examples/ (this repo) -``` - -## Testing Your Example - -```bash -# Run the example -cd my-example -go run main.go - -# Run E2E tests -go test -v - -# Test all examples together -cd .. -./test-all.sh -``` - -## Submitting Your Example - -1. Fork the repository -2. Create a branch: `git checkout -b example/my-example` -3. Add your example -4. Update main README.md -5. Test thoroughly -6. Commit: `git commit -m "Add my-example demonstrating X"` -7. Push: `git push origin example/my-example` -8. Create Pull Request - -## Example Categories - -Consider these categories for new examples: - -- **Basic**: Simple concepts (counter, hello world) -- **CRUD**: Database operations -- **Real-time**: WebSocket, chat, collaboration -- **Forms**: Validation, file uploads -- **Authentication**: Login, sessions, JWT -- **Testing**: E2E patterns, test helpers -- **Production**: Deployment, monitoring, scaling -- **Patterns**: Common UI patterns, best practices - -## Code Style - -- Use `gofmt` for formatting -- Follow [Effective Go](https://go.dev/doc/effective_go) -- Keep functions focused and small -- Add godoc comments for exported functions - -## Questions? - -- **Issues**: [GitHub Issues](https://github.com/livetemplate/examples/issues) -- **Discussions**: [GitHub Discussions](https://github.com/livetemplate/examples/discussions) - -## License - -By contributing, you agree that your contributions will be licensed under the MIT License. +This page is about example apps. For the framework itself, see +[LiveTemplate](/contributing/livetemplate), [the browser +client](/contributing/client), or [the CLI](/contributing/cli).