Skip to content

Commit 48ab0d4

Browse files
MiguelLZPFMiguelLZPF
committed
feat: sync CODEOWNERS-protected infrastructure files from develop to main
Updates CODEOWNERS-protected CI/CD files from develop branch: Workflow files (8 updated/new): - ats.publish.yml: Added ref input, fixed release tag matching, improved Node version and access flags - ats.release.yml: Added release authorization checks, enhanced validation and changelog generation - ats.test.yml: Updated to Node 22.x - changeset-check.yml: Enhanced changeset validation logic - mp.publish.yml: Synchronized with ATS improvements - mp.release.yml: Updated release workflow - mp.test.yml: Node version updates - workflows/README.md: New comprehensive CI/CD documentation Configuration files (1 updated): - .gitignore: Updated patterns Part 1/2 of develop->main sync (infrastructure changes only) Signed-off-by: Miguel_LZPF <[email protected]>
1 parent 82f334a commit 48ab0d4

File tree

9 files changed

+566
-160
lines changed

9 files changed

+566
-160
lines changed

‎.github/workflows/README.md‎

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
# GitHub Workflows Documentation
2+
3+
This document explains the CI/CD system for the Asset Tokenization Studio (ATS) monorepo, including development workflow, release processes, and how to work with changesets.
4+
5+
## Overview
6+
7+
The repository uses **Changesets** for version management with independent release cycles for:
8+
9+
- **ATS Project**: Asset Tokenization Studio (contracts, SDK, web app)
10+
- **Mass Payout Project**: Mass payout functionality
11+
12+
All development happens on the `develop` branch with automated testing, changeset validation, and manual release controls by authorized teams.
13+
14+
## Developer Workflow
15+
16+
### Daily Development Process
17+
18+
```mermaid
19+
sequenceDiagram
20+
participant D as develop
21+
participant F as feature/branch
22+
participant M as main
23+
participant F1 as feature/branch-main
24+
25+
Note over D,M: Daily Development Pattern
26+
27+
D->>F: Create feature branch
28+
Note over F: Code changes + changeset
29+
F->>D: PR with changeset (tests + validation)
30+
Note over D: Accumulate features
31+
32+
D->>F1: Create branch from develop
33+
Note over F1: Same changes (no changeset needed)
34+
F1->>M: PR to main (ready for release)
35+
Note over M: Production-ready code
36+
```
37+
38+
### Step-by-Step Guide
39+
40+
1. **Create feature branch from develop**:
41+
42+
```bash
43+
git checkout develop && git pull origin develop
44+
git checkout -b feature/your-feature-name
45+
```
46+
47+
2. **Make your changes** to ATS or Mass Payout packages
48+
49+
3. **Create changeset** (required for all PRs):
50+
51+
```bash
52+
npm run changeset
53+
```
54+
55+
- Select affected packages
56+
- Choose change type (patch/minor/major)
57+
- Write clear description
58+
59+
4. **Commit with DCO and Signature compliance**:
60+
61+
```bash
62+
git add .
63+
git commit --signoff -S -m "feat: your commit message"
64+
git push origin feature/your-feature-name
65+
```
66+
67+
5. **Open PR to develop branch** - automated checks will run
68+
69+
### Bypass Changeset Validation
70+
71+
For non-feature changes, add these labels to skip changeset requirement:
72+
73+
- `no-changeset`: Configuration or documentation changes
74+
- `docs-only`: Documentation-only changes
75+
- `chore`: Build system or dependency updates
76+
- `hotfix`: Emergency fixes
77+
78+
## Workflow Reference
79+
80+
### Automated Workflows
81+
82+
| Workflow | Trigger | Purpose |
83+
| --------------------- | ---------------------------- | ------------------------------------- |
84+
| **ATS Tests** | PR to main, ATS file changes | Run ATS contracts, SDK, and web tests |
85+
| **Mass Payout Tests** | PR to main, MP file changes | Run Mass Payout package tests |
86+
| **Changeset Check** | PR to develop | Validate changeset or bypass labels |
87+
88+
### Manual Release Workflows
89+
90+
| Workflow | Purpose | Authorized Teams |
91+
| ----------------------- | ------------------------------------ | ------------------------------------------------------------ |
92+
| **ATS Release** | Version ATS packages, create release | platform-ci, release-engineering-managers, iobuilders-hedera |
93+
| **Mass Payout Release** | Version MP packages, create release | platform-ci, release-engineering-managers, iobuilders-hedera |
94+
95+
### Automatic Publishing
96+
97+
| Workflow | Trigger | Purpose |
98+
| ----------------------- | ------------------- | --------------------------- |
99+
| **ATS Publish** | Release tag `*-ats` | Publish ATS packages to npm |
100+
| **Mass Payout Publish** | Release tag `*-mp` | Publish MP packages to npm |
101+
102+
## Release Process
103+
104+
The repository supports **two release approaches**:
105+
106+
1. **Automated Release Workflows** (recommended for most releases)
107+
2. **Manual Release Branches** (alternative for complex releases or when automation is unavailable)
108+
109+
### Option 1: Automated Release Workflows
110+
111+
#### ATS Release Flow
112+
113+
```mermaid
114+
sequenceDiagram
115+
participant Dev as Developer
116+
participant M as main
117+
participant GH as GitHub Actions
118+
participant NPM as NPM Registry
119+
120+
Dev->>GH: Trigger ATS Release Workflow
121+
GH->>GH: Validate ATS changesets exist
122+
GH->>M: Run changeset version --ignore MP
123+
GH->>M: Commit version changes to main
124+
GH->>M: Create tag v1.16.0-ats
125+
GH->>GH: Create GitHub release
126+
GH->>NPM: Auto-trigger publish workflow
127+
NPM->>NPM: Publish contracts & SDK
128+
```
129+
130+
#### Mass Payout Release Flow
131+
132+
```mermaid
133+
sequenceDiagram
134+
participant Dev as Developer
135+
participant M as main
136+
participant GH as GitHub Actions
137+
participant NPM as NPM Registry
138+
139+
Dev->>GH: Trigger MP Release Workflow
140+
GH->>GH: Validate MP changesets exist
141+
GH->>M: Run changeset version --ignore ATS
142+
GH->>M: Commit version changes to main
143+
GH->>M: Create tag v2.4.0-mp
144+
GH->>GH: Create GitHub release
145+
GH->>NPM: Auto-trigger publish workflow
146+
NPM->>NPM: Publish MP packages
147+
```
148+
149+
#### Release Options
150+
151+
Both automated workflows support:
152+
153+
- **Preview Mode**: Shows what would be released (dry-run)
154+
- **Release Mode**: Actually creates releases and triggers publishing
155+
156+
### Option 2: Manual Release Branches
157+
158+
For complex releases or when automation is unavailable, you can use the traditional manual release branch approach:
159+
160+
```mermaid
161+
sequenceDiagram
162+
participant M as main
163+
participant D as develop
164+
participant F as feat/example
165+
participant F1 as feat/example-main
166+
participant R as release/v1.22.2-ats
167+
168+
Note over M,D: Initial state
169+
170+
loop for each feature in sprint
171+
D->>F: Create feature branch
172+
Note over F: Feature development + changeset
173+
F->>D: Merge PR with changeset
174+
175+
D->>F1: Create branch from develop
176+
F1->>M: Merge PR directly to main
177+
end
178+
179+
M->>R: Create release branch
180+
Note over R: Run: npx changeset version
181+
Note over R: Generate changelogs + version bump
182+
R->>M: Merge version commit to main
183+
184+
Note over M: Create tag v1.22.2-ats
185+
Note over M: Manual GitHub release
186+
Note over M: Automatic NPM publish via workflow
187+
188+
M->>D: Merge main back to develop
189+
```
190+
191+
#### Manual Release Steps
192+
193+
1. **Create release branch from main**:
194+
195+
```bash
196+
git checkout main && git pull origin main
197+
git checkout -b release/v1.22.2-ats
198+
```
199+
200+
2. **Apply changesets and version packages**:
201+
202+
```bash
203+
# For ATS release
204+
npx changeset version --ignore "@hashgraph/mass-payout*"
205+
206+
# For Mass Payout release
207+
npx changeset version --ignore "@hashgraph/asset-tokenization-*"
208+
```
209+
210+
3. **Commit version changes**:
211+
212+
```bash
213+
git add .
214+
git commit --signoff -S -m "chore: release v1.22.2-ats"
215+
git push origin release/v1.22.2-ats
216+
```
217+
218+
4. **Merge release branch to main**:
219+
- Create PR from `release/v1.22.2-ats` to `main`
220+
- Review and merge the version changes
221+
222+
5. **Create GitHub release**:
223+
- Create tag `v1.22.2-ats` on main branch
224+
- Create GitHub release with generated changelog
225+
- Publishing workflows trigger automatically
226+
227+
6. **Sync main back to develop**:
228+
```bash
229+
git checkout develop
230+
git merge main
231+
git push origin develop
232+
```
233+
234+
**Benefits of Manual Release Branches**:
235+
236+
- ✅ Full control over version timing and content
237+
- ✅ Ability to make additional changes during release process
238+
- ✅ Works with existing automated publishing workflows
239+
- ✅ Suitable for complex releases requiring manual intervention
240+
241+
### Release Authorization
242+
243+
Only these teams can trigger releases:
244+
245+
- `platform-ci`
246+
- `platform-ci-committers`
247+
- `release-engineering-managers`
248+
- `developer-advocates`
249+
- `iobuilders-hedera`
250+
- Users containing `hashgraph`
251+
252+
## Workflow Interactions
253+
254+
```mermaid
255+
sequenceDiagram
256+
participant D as develop
257+
participant M as main
258+
participant GH as GitHub Actions
259+
participant NPM as NPM Registry
260+
261+
Note over D,M: Workflow Overview
262+
263+
loop Feature Development
264+
Note over D: Features merge to develop
265+
Note over D: Changesets accumulate
266+
D->>M: Feature PRs to main
267+
end
268+
269+
Note over M: Ready for release
270+
M->>GH: Manual release trigger
271+
GH->>M: Version packages + create tag
272+
GH->>GH: Create GitHub release
273+
GH->>NPM: Auto-trigger publish
274+
NPM->>NPM: Publish to NPM
275+
276+
M->>D: Sync version changes back
277+
```
278+
279+
## Troubleshooting
280+
281+
### Common Issues
282+
283+
**❌ Changeset check failed**
284+
285+
- **Solution**: Create changeset with `npm run changeset` or add bypass label
286+
287+
**❌ "No changesets found to be bumped"**
288+
289+
- **Solution**: Ensure changesets exist for the project you're releasing
290+
- Use `npm run changeset:status` to check pending changes
291+
292+
**❌ Release workflow unauthorized**
293+
294+
- **Solution**: Ensure you're member of authorized teams listed in CODEOWNERS
295+
296+
**❌ Tests failing on PR**
297+
298+
- **Solution**: Run `npm run ats:test` or `npm run mass-payout:test` locally
299+
- Fix failing tests before requesting review
300+
301+
**❌ DCO check failed**
302+
303+
- **Solution**: Ensure all commits use `--signoff` flag:
304+
```bash
305+
git commit --signoff -S -m "your message"
306+
```
307+
308+
### Getting Help
309+
310+
- **Changesets documentation**: [Changesets Intro](https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md)
311+
- **Check pending releases**: `npm run changeset:status`
312+
- **Preview releases**: `npm run release:preview`
313+
- **Local development**: See `CLAUDE.md` for complete development setup
314+
315+
## Quick Commands
316+
317+
```bash
318+
# Development
319+
npm run changeset # Create changeset
320+
npm run changeset:status # Check pending changes
321+
npm run ats:test # Run ATS tests
322+
npm run mass-payout:test # Run MP tests
323+
324+
# Preview releases
325+
npm run release:preview # Show all pending releases
326+
npm run release:ats # Preview ATS release (local)
327+
npm run release:mp # Preview MP release (local)
328+
```

0 commit comments

Comments
 (0)