Skip to content

Commit 6313b95

Browse files
tmigonetmigone
committed
feat: deployment strategy proposal
Signed-off-by: Tomás Migone <tomas@edgeandnode.com>
1 parent 7ad4e8b commit 6313b95

3 files changed

Lines changed: 184 additions & 2 deletions

File tree

‎.github/workflows/deployment-tag.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Tag Deployment
2+
3+
on:
4+
push:
5+
branches:
6+
- deployed/testnet
7+
- deployed/mainnet
8+
9+
jobs:
10+
tag-deployment:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: write
14+
steps:
15+
- uses: actions/checkout@v4
16+
with:
17+
fetch-tags: true
18+
19+
- name: Extract network from branch
20+
id: network
21+
run: |
22+
BRANCH="${GITHUB_REF#refs/heads/}"
23+
NETWORK="${BRANCH#deployed/}"
24+
echo "network=$NETWORK" >> $GITHUB_OUTPUT
25+
26+
- name: Generate tag name
27+
id: tag
28+
run: |
29+
NETWORK="${{ steps.network.outputs.network }}"
30+
DATE=$(date -u +%Y-%m-%d)
31+
BASE_TAG="deploy/${NETWORK}/${DATE}"
32+
33+
# Check if tag already exists, add suffix if needed
34+
COUNT=1
35+
TAG="$BASE_TAG"
36+
37+
while git rev-parse "$TAG" >/dev/null 2>&1; do
38+
COUNT=$((COUNT + 1))
39+
TAG="${BASE_TAG}-${COUNT}"
40+
done
41+
42+
echo "tag=$TAG" >> $GITHUB_OUTPUT
43+
44+
- name: Create and push tag
45+
run: |
46+
TAG="${{ steps.tag.outputs.tag }}"
47+
NETWORK="${{ steps.network.outputs.network }}"
48+
git config user.name "github-actions"
49+
git config user.email "github-actions@github.com"
50+
git tag -a "$TAG" -m "Deployment to ${NETWORK} on $(date -u +%Y-%m-%d)"
51+
git push origin "$TAG"
52+
echo "## Deployment Tagged" >> $GITHUB_STEP_SUMMARY
53+
echo "- **Network:** ${NETWORK}" >> $GITHUB_STEP_SUMMARY
54+
echo "- **Tag:** $TAG" >> $GITHUB_STEP_SUMMARY
55+
echo "- **Commit:** ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY

‎DEPLOYMENT.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Deployment Strategy
2+
3+
This document outlines the branching and deployment strategy for Solidity contracts in this repository.
4+
5+
## Overview
6+
7+
We use a **promotion-based deployment model** where code flows from development through testnet to mainnet via pull requests. This ensures clear traceability of what code is deployed where.
8+
9+
```
10+
feature/* ────────────────┐
11+
▼
12+
main (deployment-ready)
13+
│
14+
▼ PR (testnet deployment)
15+
deployed/testnet ──► tag: deploy/testnet/YYYY-MM-DD
16+
│
17+
▼ PR (mainnet deployment)
18+
deployed/mainnet ──► tag: deploy/mainnet/YYYY-MM-DD
19+
```
20+
21+
## Key Principles
22+
23+
1. **Work in feature branches.** All development happens in `feature/*` branches. Merge to `main` only when the work is complete.
24+
25+
2. **`main` is always deployable.** If code isn't ready for deployment, it stays in a feature branch. This also means code in `main` must be audited.
26+
27+
3. **`deployed/*` branches are append-only.** They only move forward via PRs, merging everything accumulated. This keeps history clean and ensures testnet accurately previews what will go to mainnet. Exception: emergency hotfixes.
28+
29+
4. **Tag every deployment.** Each merge to a deployment branch creates a tag (e.g., `deploy/mainnet/2026-04-16`) as an immutable historical record.
30+
31+
5. **Backport hotfixes.** If you fix something directly on a deployment branch, merge that fix back to `main` to prevent regression.
32+
33+
## Branches
34+
35+
| Branch | Purpose | Contains |
36+
|--------|---------|----------|
37+
| `feature/*` | Active development | Work-in-progress, not yet deployment-ready |
38+
| `main` | Development head | Latest **deployment-ready** code |
39+
| `deployed/testnet` | Testnet deployment tracking | Exactly what's deployed on Arbitrum Sepolia |
40+
| `deployed/mainnet` | Mainnet deployment tracking | Exactly what's deployed on Arbitrum One |
41+
42+
### Finding deployed code
43+
44+
To see exactly what code is running on a network:
45+
46+
```bash
47+
# What's on mainnet?
48+
git checkout deployed/mainnet
49+
50+
# What's on testnet?
51+
git checkout deployed/testnet
52+
53+
# What's pending deployment (in main but not yet on mainnet)?
54+
git diff deployed/mainnet..main
55+
```
56+
57+
## Tags
58+
59+
Each deployment automatically creates a tag for historical reference:
60+
61+
- `deploy/testnet/YYYY-MM-DD` — Testnet deployment snapshots
62+
- `deploy/mainnet/YYYY-MM-DD` — Mainnet deployment snapshots
63+
64+
List all deployment tags:
65+
66+
```bash
67+
git tag -l "deploy/*"
68+
```
69+
70+
## Workflows
71+
72+
### Feature Development
73+
74+
Features are developed in feature branches and merged to `main` when complete.
75+
76+
```
77+
feature/new-stuff ──PR──► main
78+
```
79+
80+
### Testnet Deployment
81+
82+
When ready to deploy to testnet:
83+
84+
1. Create a PR from `main` to `deployed/testnet`
85+
2. Review and merge the PR
86+
3. Create tag `deploy/testnet/YYYY-MM-DD`
87+
4. Deploy the contracts to Arbitrum Sepolia
88+
89+
```
90+
main ──PR──► deployed/testnet ──► tag: deploy/testnet/YYYY-MM-DD
91+
```
92+
93+
### Mainnet Deployment
94+
95+
When ready to deploy to mainnet (typically after testnet validation and audit):
96+
97+
1. Create a PR from `deployed/testnet` to `deployed/mainnet`
98+
2. Review and merge the PR
99+
3. Create tag `deploy/mainnet/YYYY-MM-DD`
100+
4. Deploy the contracts to Arbitrum One
101+
102+
```
103+
deployed/testnet ──PR──► deployed/mainnet ──► tag: deploy/mainnet/YYYY-MM-DD
104+
```
105+
106+
### Emergency Hotfix
107+
108+
For critical mainnet issues that cannot wait for the normal flow:
109+
110+
1. Branch from `deployed/mainnet`
111+
2. Apply the fix
112+
3. PR directly to `deployed/mainnet`
113+
4. Tag and deploy
114+
5. **Backport the fix to `main`** to prevent regression
115+
116+
```
117+
deployed/mainnet ◄── hotfix/critical-fix
118+
│
119+
├──► tag: deploy/mainnet/YYYY-MM-DD
120+
│
121+
└──► PR to main (backport)
122+
```
123+
124+
## Auto-tagging
125+
126+
A GitHub Action (`.github/workflows/deployment-tag.yml`) automatically creates deployment tags when PRs are merged to deployment branches. No manual tagging is required.

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -178,9 +178,10 @@ See [docs/Linting.md](docs/Linting.md) for detailed configuration, inline suppre
178178

179179
## Documentation
180180

181-
> Coming soon
181+
- [Deployment Strategy](DEPLOYMENT.md) — Branching model and deployment workflow for Solidity contracts
182+
- [Linting](docs/Linting.md) — Linting configuration and troubleshooting
182183

183-
For now, each package has its own README with more specific documentation you can check out.
184+
Each package also has its own README with package-specific documentation.
184185

185186
## Contributing
186187

0 commit comments

Comments
 (0)