Skip to content

Commit 71ce4ca

Browse files
auricomauricom
committed
docs
1 parent dd4a854 commit 71ce4ca

3 files changed

Lines changed: 234 additions & 2 deletions

File tree

‎.github/RELEASE_QUICK_START.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# Quick Start: Release Guide
2+
3+
This is a quick reference guide for releasing ev-node components. For detailed documentation, see:
4+
- **Workflow Details**: [.github/workflows/README.md](workflows/README.md)
5+
- **Complete Release Process**: [RELEASE.md](../RELEASE.md)
6+
7+
## Docker Image Release (Recommended for Apps)
8+
9+
### When to Use
10+
Release deployable applications (EVM nodes, test apps, etc.) as Docker images.
11+
12+
### Quick Steps
13+
14+
```bash
15+
# 1. Ensure CI passes on main
16+
# 2. Create and push tag
17+
git tag evm/single/v0.2.0
18+
git push origin evm/single/v0.2.0
19+
20+
# 3. Monitor workflow
21+
# GitHub → Actions → Release workflow
22+
23+
# 4. Verify release
24+
docker pull ghcr.io/evstack/ev-node-evm-single:v0.2.0
25+
```
26+
27+
### Tag Format
28+
`{app-path}/v{major}.{minor}.{patch}`
29+
30+
**Examples:**
31+
- `evm/single/v0.2.0` → Releases `apps/evm/single/`
32+
- `testapp/v1.0.0` → Releases `apps/testapp/`
33+
- `grpc/single/v2.1.3` → Releases `apps/grpc/single/`
34+
35+
### What Happens Automatically
36+
1. ✅ Validates tag and app directory
37+
2. ✅ Builds multi-platform Docker image (amd64, arm64)
38+
3. ✅ Publishes to GHCR:
39+
- Version tag: `ghcr.io/evstack/ev-node-{app}:v0.2.0`
40+
- Latest tag: `ghcr.io/evstack/ev-node-{app}:latest`
41+
42+
### Requirements
43+
- App directory exists: `./apps/{app-path}/`
44+
- Dockerfile exists: `./apps/{app-path}/Dockerfile`
45+
- Tag format: `**/v*.*.*`
46+
- CI passes on main branch
47+
48+
---
49+
50+
## Go Module Release (For Libraries)
51+
52+
### When to Use
53+
Release Go library packages (core, da, sequencers, etc.) for use as dependencies.
54+
55+
### Quick Steps
56+
57+
```bash
58+
# 1. Release in dependency order
59+
# 2. Wait for Go proxy propagation between releases
60+
# 3. Update dependent modules before releasing them
61+
62+
# Example: Release core module
63+
cd core
64+
git tag core/v0.3.0
65+
git push origin core/v0.3.0
66+
67+
# Wait 5-10 minutes for Go proxy
68+
go list -m github.com/evstack/ev-node/core@v0.3.0
69+
```
70+
71+
### Release Order
72+
1. **Phase 1**: `core` (no dependencies)
73+
2. **Phase 2**: `da`, `ev-node`, `execution/evm` (depend on core)
74+
3. **Phase 3**: `sequencers/*` (depend on core + ev-node)
75+
4. **Phase 4**: `apps/*` (depend on all previous)
76+
77+
**See [RELEASE.md](../RELEASE.md#go-module-releases-manual) for complete dependency graph and detailed steps.**
78+
79+
---
80+
81+
## Common Release Scenarios
82+
83+
### Scenario 1: Release Single App (Docker)
84+
```bash
85+
# Tag and push
86+
git tag evm/single/v0.2.0
87+
git push origin evm/single/v0.2.0
88+
89+
# Done! Automated workflow handles the rest
90+
```
91+
92+
### Scenario 2: Release Multiple Apps
93+
```bash
94+
# Release apps independently
95+
git tag evm/single/v0.2.0
96+
git tag testapp/v1.0.0
97+
git push origin evm/single/v0.2.0 testapp/v1.0.0
98+
99+
# Each triggers its own workflow
100+
```
101+
102+
### Scenario 3: Full Go Module Release
103+
```bash
104+
# 1. Core
105+
git tag core/v0.3.0 && git push origin core/v0.3.0
106+
107+
# 2. Wait 5-10 min, then first-level deps
108+
git tag da/v0.3.0 && git push origin da/v0.3.0
109+
git tag v0.3.0 && git push origin v0.3.0
110+
git tag execution/evm/v0.3.0 && git push origin execution/evm/v0.3.0
111+
112+
# 3. Wait, then sequencers
113+
git tag sequencers/single/v0.3.0 && git push origin sequencers/single/v0.3.0
114+
115+
# 4. Wait, then apps
116+
git tag apps/evm/single/v0.3.0 && git push origin apps/evm/single/v0.3.0
117+
```
118+
119+
### Scenario 4: Hotfix/Rollback
120+
```bash
121+
# Delete bad tag
122+
git tag -d evm/single/v0.2.0
123+
git push origin :refs/tags/evm/single/v0.2.0
124+
125+
# Fix code, create new tag
126+
git tag evm/single/v0.2.1
127+
git push origin evm/single/v0.2.1
128+
```
129+
130+
---
131+
132+
## Verification
133+
134+
### Docker Image Release
135+
```bash
136+
# Check workflow status
137+
# GitHub → Actions → Release
138+
139+
# Pull and test image
140+
docker pull ghcr.io/evstack/ev-node-evm-single:v0.2.0
141+
docker run ghcr.io/evstack/ev-node-evm-single:v0.2.0 --version
142+
143+
# Check GHCR
144+
# GitHub → Packages → ev-node-evm-single
145+
```
146+
147+
### Go Module Release
148+
```bash
149+
# Verify module is available
150+
go list -m github.com/evstack/ev-node/core@v0.3.0
151+
152+
# Test in a consumer project
153+
go get github.com/evstack/ev-node/core@v0.3.0
154+
```
155+
156+
---
157+
158+
## Troubleshooting
159+
160+
### "App directory does not exist"
161+
- Ensure tag matches app path: `apps/evm/single/` → `evm/single/v0.2.0`
162+
- Check spelling and case sensitivity
163+
164+
### "Dockerfile not found"
165+
- Verify Dockerfile exists at `apps/{app-path}/Dockerfile`
166+
- Check file name is exactly `Dockerfile`
167+
168+
### "Image not found" in tests
169+
- Wait for Docker build workflow to complete
170+
- Check workflow dependencies in Actions tab
171+
172+
### Go proxy delay
173+
- Wait 5-30 minutes for propagation
174+
- Use `go list -m` to verify availability
175+
- Check https://proxy.golang.org/
176+
177+
---
178+
179+
## Best Practices
180+
181+
### Before Releasing
182+
183+
- ✅ All changes merged to `main`
184+
- ✅ CI workflow passes
185+
- ✅ CHANGELOG.md updated
186+
- ✅ Documentation updated
187+
- ✅ Local testing complete
188+
189+
### Semantic Versioning
190+
191+
- **Major (v2.0.0)**: Breaking changes
192+
- **Minor (v1.1.0)**: New features, backward compatible
193+
- **Patch (v1.0.1)**: Bug fixes, backward compatible
194+
195+
### Tag Messages
196+
197+
```bash
198+
# Good: Annotated tag with description
199+
git tag -a evm/single/v0.2.0 -m "Release EVM single v0.2.0
200+
201+
Features:
202+
- Added feature X
203+
- Improved performance Y
204+
205+
Bug fixes:
206+
- Fixed issue Z
207+
"
208+
209+
# Avoid: Lightweight tag without description
210+
git tag evm/single/v0.2.0 # Less informative
211+
```
212+
213+
---
214+
215+
## Quick Links
216+
217+
- **Workflow Details**: [.github/workflows/README.md](workflows/README.md)
218+
- **Complete Release Process**: [RELEASE.md](../RELEASE.md)
219+
- **CI Workflow**: [.github/workflows/ci.yml](workflows/ci.yml)
220+
- **Release Workflow**: [.github/workflows/release.yml](workflows/release.yml)
221+
- **GitHub Actions**: https://github.com/evstack/ev-node/actions
222+
- **GitHub Packages**: https://github.com/orgs/evstack/packages
223+
224+
---
225+
226+
## Need Help?
227+
228+
1. **Workflow documentation**: See [.github/workflows/README.md](workflows/README.md)
229+
2. **Release process**: See [RELEASE.md](../RELEASE.md)
230+
3. **CI failures**: Check GitHub Actions logs
231+
4. **Questions**: Open an issue or discussion

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ on:
66
pull_request:
77
merge_group:
88

9+
permissions: {}
910
jobs:
1011
determine-image-tag:
1112
name: Determine Image Tag
@@ -52,7 +53,7 @@ jobs:
5253
image-tag: ${{ needs.determine-image-tag.outputs.tag }}
5354
apps: |
5455
[
55-
{"name": "ev-node-evm-single", "dockerfile": "apps/evm/single/Dockerfile"},
56+
{"name": "ev-node-evm-single", "dockerfile": "apps/evm/single/Dockerfile"}
5657
]
5758
5859
test:

‎.github/workflows/docker-tests.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ jobs:
3030
- name: Run Docker E2E Tests
3131
run: make test-docker-e2e
3232
env:
33-
EV_NODE_IMAGE_REPO: ghcr.io/${{ github.repository }}
33+
EV_NODE_IMAGE_REPO: ghcr.io/${{ github.repository_owner }}
3434
EV_NODE_IMAGE_TAG: ${{ inputs.image-tag }}
3535

3636
docker-upgrade-tests:

0 commit comments

Comments
 (0)