Skip to content

chore: sync CODEOWNERS-protected infrastructure files from develop #710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
MiguelLZPF wants to merge 1 commit into from
Closed

chore: sync CODEOWNERS-protected infrastructure files from develop #710

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
328 changes: 328 additions & 0 deletions .github/workflows/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,328 @@
# GitHub Workflows Documentation

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.

## Overview

The repository uses **Changesets** for version management with independent release cycles for:

- **ATS Project**: Asset Tokenization Studio (contracts, SDK, web app)
- **Mass Payout Project**: Mass payout functionality

All development happens on the `develop` branch with automated testing, changeset validation, and manual release controls by authorized teams.

## Developer Workflow

### Daily Development Process

```mermaid
sequenceDiagram
participant D as develop
participant F as feature/branch
participant M as main
participant F1 as feature/branch-main

Note over D,M: Daily Development Pattern

D->>F: Create feature branch
Note over F: Code changes + changeset
F->>D: PR with changeset (tests + validation)
Note over D: Accumulate features

D->>F1: Create branch from develop
Note over F1: Same changes (no changeset needed)
F1->>M: PR to main (ready for release)
Note over M: Production-ready code
```

### Step-by-Step Guide

1. **Create feature branch from develop**:

```bash
git checkout develop && git pull origin develop
git checkout -b feature/your-feature-name
```

2. **Make your changes** to ATS or Mass Payout packages

3. **Create changeset** (required for all PRs):

```bash
npm run changeset
```

- Select affected packages
- Choose change type (patch/minor/major)
- Write clear description

4. **Commit with DCO and Signature compliance**:

```bash
git add .
git commit --signoff -S -m "feat: your commit message"
git push origin feature/your-feature-name
```

5. **Open PR to develop branch** - automated checks will run

### Bypass Changeset Validation

For non-feature changes, add these labels to skip changeset requirement:

- `no-changeset`: Configuration or documentation changes
- `docs-only`: Documentation-only changes
- `chore`: Build system or dependency updates
- `hotfix`: Emergency fixes

## Workflow Reference

### Automated Workflows

| Workflow | Trigger | Purpose |
| --------------------- | ---------------------------- | ------------------------------------- |
| **ATS Tests** | PR to main, ATS file changes | Run ATS contracts, SDK, and web tests |
| **Mass Payout Tests** | PR to main, MP file changes | Run Mass Payout package tests |
| **Changeset Check** | PR to develop | Validate changeset or bypass labels |

### Manual Release Workflows

| Workflow | Purpose | Authorized Teams |
| ----------------------- | ------------------------------------ | ------------------------------------------------------------ |
| **ATS Release** | Version ATS packages, create release | platform-ci, release-engineering-managers, iobuilders-hedera |
| **Mass Payout Release** | Version MP packages, create release | platform-ci, release-engineering-managers, iobuilders-hedera |

### Automatic Publishing

| Workflow | Trigger | Purpose |
| ----------------------- | ------------------- | --------------------------- |
| **ATS Publish** | Release tag `*-ats` | Publish ATS packages to npm |
| **Mass Payout Publish** | Release tag `*-mp` | Publish MP packages to npm |

## Release Process

The repository supports **two release approaches**:

1. **Automated Release Workflows** (recommended for most releases)
2. **Manual Release Branches** (alternative for complex releases or when automation is unavailable)

### Option 1: Automated Release Workflows

#### ATS Release Flow

```mermaid
sequenceDiagram
participant Dev as Developer
participant M as main
participant GH as GitHub Actions
participant NPM as NPM Registry

Dev->>GH: Trigger ATS Release Workflow
GH->>GH: Validate ATS changesets exist
GH->>M: Run changeset version --ignore MP
GH->>M: Commit version changes to main
GH->>M: Create tag v1.16.0-ats
GH->>GH: Create GitHub release
GH->>NPM: Auto-trigger publish workflow
NPM->>NPM: Publish contracts & SDK
```

#### Mass Payout Release Flow

```mermaid
sequenceDiagram
participant Dev as Developer
participant M as main
participant GH as GitHub Actions
participant NPM as NPM Registry

Dev->>GH: Trigger MP Release Workflow
GH->>GH: Validate MP changesets exist
GH->>M: Run changeset version --ignore ATS
GH->>M: Commit version changes to main
GH->>M: Create tag v2.4.0-mp
GH->>GH: Create GitHub release
GH->>NPM: Auto-trigger publish workflow
NPM->>NPM: Publish MP packages
```

#### Release Options

Both automated workflows support:

- **Preview Mode**: Shows what would be released (dry-run)
- **Release Mode**: Actually creates releases and triggers publishing

### Option 2: Manual Release Branches

For complex releases or when automation is unavailable, you can use the traditional manual release branch approach:

```mermaid
sequenceDiagram
participant M as main
participant D as develop
participant F as feat/example
participant F1 as feat/example-main
participant R as release/v1.22.2-ats

Note over M,D: Initial state

loop for each feature in sprint
D->>F: Create feature branch
Note over F: Feature development + changeset
F->>D: Merge PR with changeset

D->>F1: Create branch from develop
F1->>M: Merge PR directly to main
end

M->>R: Create release branch
Note over R: Run: npx changeset version
Note over R: Generate changelogs + version bump
R->>M: Merge version commit to main

Note over M: Create tag v1.22.2-ats
Note over M: Manual GitHub release
Note over M: Automatic NPM publish via workflow

M->>D: Merge main back to develop
```

#### Manual Release Steps

1. **Create release branch from main**:

```bash
git checkout main && git pull origin main
git checkout -b release/v1.22.2-ats
```

2. **Apply changesets and version packages**:

```bash
# For ATS release
npx changeset version --ignore "@hashgraph/mass-payout*"

# For Mass Payout release
npx changeset version --ignore "@hashgraph/asset-tokenization-*"
```

3. **Commit version changes**:

```bash
git add .
git commit --signoff -S -m "chore: release v1.22.2-ats"
git push origin release/v1.22.2-ats
```

4. **Merge release branch to main**:
- Create PR from `release/v1.22.2-ats` to `main`
- Review and merge the version changes

5. **Create GitHub release**:
- Create tag `v1.22.2-ats` on main branch
- Create GitHub release with generated changelog
- Publishing workflows trigger automatically

6. **Sync main back to develop**:
```bash
git checkout develop
git merge main
git push origin develop
```

**Benefits of Manual Release Branches**:

- ✅ Full control over version timing and content
- ✅ Ability to make additional changes during release process
- ✅ Works with existing automated publishing workflows
- ✅ Suitable for complex releases requiring manual intervention

### Release Authorization

Only these teams can trigger releases:

- `platform-ci`
- `platform-ci-committers`
- `release-engineering-managers`
- `developer-advocates`
- `iobuilders-hedera`
- Users containing `hashgraph`

## Workflow Interactions

```mermaid
sequenceDiagram
participant D as develop
participant M as main
participant GH as GitHub Actions
participant NPM as NPM Registry

Note over D,M: Workflow Overview

loop Feature Development
Note over D: Features merge to develop
Note over D: Changesets accumulate
D->>M: Feature PRs to main
end

Note over M: Ready for release
M->>GH: Manual release trigger
GH->>M: Version packages + create tag
GH->>GH: Create GitHub release
GH->>NPM: Auto-trigger publish
NPM->>NPM: Publish to NPM

M->>D: Sync version changes back
```

## Troubleshooting

### Common Issues

**❌ Changeset check failed**

- **Solution**: Create changeset with `npm run changeset` or add bypass label

**❌ "No changesets found to be bumped"**

- **Solution**: Ensure changesets exist for the project you're releasing
- Use `npm run changeset:status` to check pending changes

**❌ Release workflow unauthorized**

- **Solution**: Ensure you're member of authorized teams listed in CODEOWNERS

**❌ Tests failing on PR**

- **Solution**: Run `npm run ats:test` or `npm run mass-payout:test` locally
- Fix failing tests before requesting review

**❌ DCO check failed**

- **Solution**: Ensure all commits use `--signoff` flag:
```bash
git commit --signoff -S -m "your message"
```

### Getting Help

- **Changesets documentation**: [Changesets Intro](https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md)
- **Check pending releases**: `npm run changeset:status`
- **Preview releases**: `npm run release:preview`
- **Local development**: See `CLAUDE.md` for complete development setup

## Quick Commands

```bash
# Development
npm run changeset # Create changeset
npm run changeset:status # Check pending changes
npm run ats:test # Run ATS tests
npm run mass-payout:test # Run MP tests

# Preview releases
npm run release:preview # Show all pending releases
npm run release:ats # Preview ATS release (local)
npm run release:mp # Preview MP release (local)
```
Loading