Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
82 lines (58 loc) · 2.37 KB

CONTRIBUTING.md

File metadata and controls

82 lines (58 loc) · 2.37 KB

Contributing a New Tutorial

Want to add a new tutorial to help people learn nojs? Great! Here's how:

Step 1: Create a New Branch

Each tutorial lives on its own branch in this repo. Use a descriptive name:

git checkout -b todos-tutorial

Step 2: Create the Starter Project

Create a minimal, self-contained project following this structure:

counter-tutorial/
├── internal/app/components/
│   └── (add your components here)
├── wwwroot/
│   ├── index.html
│   ├── core.js
│   └── (wasm_exec.js — users copy this)
├── main.go
├── go.mod
├── go.sum
├── Makefile
└── README.md

Key principles:

  • Minimal scope — Focus on one feature (counter, todos, routing, etc.)
  • Stubs with TODOs — Users fill in the blanks while reading the guide
  • Standalone — No dependencies other than github.com/ForgeLogic/nojs
  • Clear Makefile — make install and make full must work out of the box

Step 3: Write the Tutorial Guide

Create a new file in docs/:

docs/your-tutorial-name.md

Structure:

  1. Introduction — What you'll build and learn
  2. Prerequisites — Go version, etc.
  3. Step-by-step instructions — Each step has code examples and explanations
  4. What Happened — The "magic" explained
  5. Next Steps — Links to more advanced features

See docs/create-first-counter.md as a template.

Step 4: Update the Main README

Add your tutorial to the README.md under "Available Tutorials".

Step 5: Submit a Pull Request

  • Push your branch to GitHub
  • Open a PR against main
  • Include a description of the tutorial and what it teaches
  • Link to the tutorial guide in your PR description

Tips for Good Tutorials

✅ Run it yourself — Make sure all code actually works before submitting
✅ Test from a fresh clone — Verify a brand new user can follow it without confusion
✅ Use concrete examples — Show real code, not pseudocode
✅ Explain the "why" — Not just "do this", but "here's why"
✅ Link forward — Point to the Quick Guide for deeper learning
✅ Keep it focused — One feature per tutorial; save advanced topics for later

Questions?

Open an issue on the main nojs repo if you have questions.