Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Claude Code Guidelines

## Documentation

- [TinyGo Sync Strategy](docs/tinygo-sync-strategy.md) - Branch structure and workflow for syncing with TinyGo upstream
69 changes: 69 additions & 0 deletions docs/tinygo-sync-strategy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# TinyGo Sync Strategy

## Goals

Establish a clear branch structure to enable us to:
- Track TinyGo official updates
- Clearly demonstrate our customizations on top of TinyGo
- Facilitate code review and maintenance

## Branch Structure

### `machine` and `device` Branches

Both branches mirror TinyGo's official `src/machine` and `src/device` modules respectively.

- **Update Source**: TinyGo release packages (e.g., [tinygo0.39.0.linux-amd64.tar.gz](https://github.com/tinygo-org/tinygo/releases))
- **Note**: TinyGo does not directly store these modules in their repository. Copy them from official release packages.
- **Platform Note**: The `src/device` and `src/machine` directories are identical across all platform release packages, so you only need to download one platform's package.
- **Rules**: Sync only, no custom modifications
- **Commit Tag**: `[SYNC] Update machine to TinyGo <version>` or `[SYNC] Update device to TinyGo <version>`

### `main` Branch
- **Responsibility**: Production code version (protected)
- **Composition**: Merged from `machine` and `device` branches + our custom modifications
- **Rules**: ⛔ No direct push, all changes must go through PR

## Workflow

### 1. Daily Development
- Create development branch from main
- Develop and commit
- Create PR to main
- Code review and merge
- Clean up development branch

### 2. Sync Upstream Updates
- Update machine/device branches (commit with `[SYNC]`)
- Create sync branch or directly create PR
- Resolve conflicts (if any)
- Code review and merge

## Practical Use Cases

### Case 1: Daily Feature Development

**Scenario**: Add new features or modifications

**Process**:
1. Create development branch
2. Develop and commit
3. Create PR to main
4. Review and merge

---

### Case 2: Merge Upstream Updates

**Scenario**: TinyGo releases new version, sync to our repository

**Notes**:
- Do not directly track upstream dev branch
- Track upstream minor version updates

**Process**:
1. Sync to machine branch (commit with `[SYNC]`)
2. Sync to device branch (commit with `[SYNC]`)
3. On main branch, sync files from machine and device branches
4. Apply our custom modifications on the updated base (if needed)
5. Create PR to main