wehub-resource-sync
164 lines
4.4 KiB
Markdown
164 lines
4.4 KiB
Markdown
# Contributing
|
|
|
|
Lessons, translations, fixes, outputs — all welcome. One contribution per pull
|
|
request keeps reviews fast and lets contributor counts and credit work
|
|
correctly.
|
|
|
|
## Important: the README and ROADMAP feed the website
|
|
|
|
`site/build.js` parses `README.md`, `ROADMAP.md`, and `glossary/terms.md` to
|
|
generate `site/data.js`. Two patterns must stay intact in any pull request that
|
|
touches those files:
|
|
|
|
- Phase headers in either `### Phase N: Name \`X lessons\`` form or
|
|
`<details><summary><b>Phase N — Name</b> ... <code>X lessons</code> ... <em>Description</em></summary>` form.
|
|
- Lesson tables with the column shape `| # | Lesson | Type | Lang |` (or
|
|
`| # | Project | Combines | Lang |` for capstone tables). The `Lang` column
|
|
accepts plain text (`Python, TypeScript`) or the legacy emoji flags
|
|
(`🐍 🟦 🦀 🟣 ⚛️`); both are parser-equivalent.
|
|
- ROADMAP status glyphs (`✅`, `🚧`, `⬚`) on phase headers and lesson rows.
|
|
Do not replace them with text — the parser keys off the exact characters.
|
|
|
|
Run `node site/build.js` after editing those files; `git diff site/data.js`
|
|
should show only the timestamp change if your edit was structural-safe.
|
|
|
|
## Ways to Contribute
|
|
|
|
### 1. Add a New Lesson
|
|
|
|
Each lesson lives in `phases/XX-phase-name/NN-lesson-name/` with this structure:
|
|
|
|
```
|
|
NN-lesson-name/
|
|
├── code/ At least one runnable implementation
|
|
├── notebook/ Jupyter notebook for experimentation (optional)
|
|
├── docs/
|
|
│ └── en.md Lesson documentation (required)
|
|
└── outputs/ Prompts, skills, or agents this lesson produces (if applicable)
|
|
```
|
|
|
|
**Lesson doc format** (`en.md`):
|
|
|
|
```markdown
|
|
# Lesson Title
|
|
|
|
> One-line motto — the core idea in one sentence.
|
|
|
|
## The Problem
|
|
|
|
Why does this matter? What can't you do without this?
|
|
|
|
## The Concept
|
|
|
|
Explain with diagrams, visuals, and intuition. Code comes later.
|
|
|
|
## Build It
|
|
|
|
Step-by-step implementation from scratch.
|
|
|
|
## Use It
|
|
|
|
Now use a real framework or library to do the same thing.
|
|
|
|
## Ship It
|
|
|
|
The prompt, skill, agent, or tool this lesson produces.
|
|
|
|
## Exercises
|
|
|
|
1. Exercise one
|
|
2. Exercise two
|
|
3. Challenge exercise
|
|
```
|
|
|
|
### 2. Add a Translation
|
|
|
|
Create a new file in any lesson's `docs/` folder:
|
|
|
|
```
|
|
docs/
|
|
├── en.md (English — always required)
|
|
├── zh.md (Chinese)
|
|
├── ja.md (Japanese)
|
|
├── es.md (Spanish)
|
|
├── hi.md (Hindi)
|
|
└── ...
|
|
```
|
|
|
|
Keep the same structure as the English version. Translate content, not code.
|
|
|
|
### 3. Add an Output
|
|
|
|
If a lesson should produce a reusable prompt, skill, agent, or MCP server:
|
|
|
|
1. Create it in the lesson's `outputs/` folder
|
|
2. Add a reference in the top-level `outputs/` index
|
|
|
|
**Prompt format:**
|
|
|
|
```markdown
|
|
---
|
|
name: prompt-name
|
|
description: What this prompt does
|
|
phase: 14
|
|
lesson: 01
|
|
---
|
|
|
|
[System prompt or template here]
|
|
```
|
|
|
|
**Skill format:**
|
|
|
|
```markdown
|
|
---
|
|
name: skill-name
|
|
description: What this skill teaches
|
|
version: 1.0.0
|
|
phase: 14
|
|
lesson: 01
|
|
tags: [agents, loops]
|
|
---
|
|
|
|
[Skill content here]
|
|
```
|
|
|
|
### 4. Fix Bugs or Improve Existing Lessons
|
|
|
|
- Fix code that doesn't run
|
|
- Improve explanations
|
|
- Add better diagrams
|
|
- Update outdated information
|
|
|
|
### 5. Add Exercises or Projects
|
|
|
|
More exercises and projects are always welcome, especially ones that connect multiple phases.
|
|
|
|
## Guidelines
|
|
|
|
- **Code must run.** Every code file should execute without errors with the listed dependencies.
|
|
- **No comments in code.** Code should be self-explanatory. Use the docs for explanation.
|
|
- **Best language for the job.** Don't force Python where TypeScript or Rust is the better choice.
|
|
- **Build from scratch first.** Always implement the concept from first principles before showing the framework version.
|
|
- **Keep it practical.** Theory serves practice, not the other way around.
|
|
- **No AI slop.** Write like a human. Be direct. Cut filler.
|
|
|
|
## Pull Request Process
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b add-lesson-phase3-gradient-descent`)
|
|
3. Make your changes
|
|
4. Ensure all code runs
|
|
5. Submit a pull request with a clear description
|
|
|
|
## Code of Conduct
|
|
|
|
See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Be kind, be helpful, be constructive.
|
|
|
|
## Style
|
|
|
|
- Direct prose. Cut filler. Match the manual's tone, not marketing copy.
|
|
- No decorative emojis in headings. Lang column emoji flags are the one
|
|
exception and only because the parser maps them.
|
|
- Code runs as-is with the dependencies listed in the lesson.
|
|
- Build from scratch first, framework second.
|