From 2a6fbc72e1d977949cf7ca7ab7755fddc59c1e47 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Fri, 28 Aug 2026 22:44:13 +0800 Subject: [PATCH] ci: enable develop branch workflow --- .github/pull_request_template.md | 9 ++++- .github/workflows/audit-pr.yml | 1 + .github/workflows/branch-policy.yml | 21 ++++++++++ .github/workflows/ci.yml | 51 ++++++++++++++++++++++++ .github/workflows/policy-tests.yml | 25 ++++++++++++ .github/workflows/pr-metadata.yml | 25 ++++++++++++ BRANCHING.md | 62 +++++++++++++++++++++++++++++ CHANGELOG.md | 9 +++++ CLAUDE.md | 9 +++++ CONTRIBUTING.md | 12 +++++- README.md | 4 +- typescript/.changeset/config.json | 2 +- 12 files changed, 225 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/branch-policy.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/policy-tests.yml create mode 100644 .github/workflows/pr-metadata.yml create mode 100644 BRANCHING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6a0946cd..8ce71397 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,6 +10,7 @@ See here for instructions: https://docs.github.com/en/authentication/managing-co @@ -20,16 +21,20 @@ Please describe the tests you've performed to verify your changes. Include relevant code samples, unit test cases, or screenshots if applicable. For TypeScript: Run `pnpm test` from the `/typescript` directory -For Python: Run `uv run pytest` from the `/python/x402` directory --> +## Branch route + +- [ ] Normal development targets `develop` +- [ ] Only `release_*` or `hotfix/*` targets `main` + ## Checklist - [ ] I have formatted and linted my code - [ ] All new and existing tests pass +- [ ] I added a Changeset for publishable package changes, or this PR does not require one - [ ] My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits diff --git a/.github/workflows/audit-pr.yml b/.github/workflows/audit-pr.yml index 9bc21413..743cd307 100644 --- a/.github/workflows/audit-pr.yml +++ b/.github/workflows/audit-pr.yml @@ -3,6 +3,7 @@ name: Audit PR on: pull_request: branches: + - develop - main types: [opened, synchronize, reopened, ready_for_review] issue_comment: diff --git a/.github/workflows/branch-policy.yml b/.github/workflows/branch-policy.yml new file mode 100644 index 00000000..5132649d --- /dev/null +++ b/.github/workflows/branch-policy.yml @@ -0,0 +1,21 @@ +name: Validate branch policy + +on: + pull_request: + branches: + - develop + - main + types: [opened, synchronize, reopened, edited] + +permissions: + contents: read + +jobs: + source-and-target: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.base.sha }} + - name: Validate pull request route + run: sh scripts/check_branch_policy.sh "${{ github.base_ref }}" "${{ github.head_ref }}" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..8e1b3696 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,51 @@ +name: TypeScript CI + +on: + pull_request: + branches: + - develop + - main + types: [opened, synchronize, reopened, ready_for_review] + +permissions: + contents: read + +concurrency: + group: typescript-ci-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + typescript-quality: + name: TypeScript quality + runs-on: ubuntu-latest + defaults: + run: + working-directory: typescript + + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v4 + with: + version: 11.1.1 + + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: pnpm + cache-dependency-path: typescript/pnpm-lock.yaml + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Check formatting + run: pnpm format:check + + - name: Check lint + run: pnpm lint:check + + - name: Build + run: pnpm build + + - name: Run unit tests + run: pnpm test diff --git a/.github/workflows/policy-tests.yml b/.github/workflows/policy-tests.yml new file mode 100644 index 00000000..308e98cf --- /dev/null +++ b/.github/workflows/policy-tests.yml @@ -0,0 +1,25 @@ +name: Test policy validators + +on: + pull_request: + branches: + - develop + - main + types: [opened, synchronize, reopened, ready_for_review] + +permissions: + contents: read + +jobs: + policy-tests: + name: Policy validator tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: Test branch policy + run: sh scripts/check_branch_policy.test.sh + - name: Test pull request metadata policy + run: node --test scripts/check_pr_metadata.test.mjs diff --git a/.github/workflows/pr-metadata.yml b/.github/workflows/pr-metadata.yml new file mode 100644 index 00000000..0272d85a --- /dev/null +++ b/.github/workflows/pr-metadata.yml @@ -0,0 +1,25 @@ +name: Validate PR metadata + +on: + pull_request: + branches: + - develop + - main + types: [opened, synchronize, reopened, edited, ready_for_review] + +permissions: + contents: read + +jobs: + pr-metadata: + name: PR metadata + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.base.sha }} + - name: Validate title and description + env: + PR_TITLE: ${{ github.event.pull_request.title }} + PR_BODY: ${{ github.event.pull_request.body }} + run: node scripts/check_pr_metadata.mjs diff --git a/BRANCHING.md b/BRANCHING.md new file mode 100644 index 00000000..ffd28fde --- /dev/null +++ b/BRANCHING.md @@ -0,0 +1,62 @@ +# Branching and Release Policy + +This repository uses a two-branch development model based on java-tron's release workflow. + +## Long-lived branches + +- `develop` is the default development and integration branch. Start normal work from `develop` + and merge it back through a pull request. +- `main` contains stable, released code. Do not send feature, fix, documentation, or upstream-sync + pull requests directly to `main`. + +Protect both branches from direct pushes, force pushes, and deletion. Require pull requests, +successful checks, review approval, and resolved conversations before merging. + +## Development branches + +Create day-to-day branches from `develop`. Supported prefixes are: + +- `feature/*` or `feat/*` for features +- `fix/*` for non-release fixes +- `docs/*`, `chore/*`, `refactor/*`, `test/*`, `perf/*`, or `ci/*` for their corresponding work +- `sync/*` for upstream synchronization + +Open these pull requests against `develop`. + +## Release branches + +When `develop` is ready for release: + +1. Create `release_vX.Y.Z` from `develop`. +2. Apply version changes, consume Changesets, update release notes, and complete regression testing + on the release branch. +3. If regression identifies a bug, merge its fix directly into the release branch and repeat the + regression test. +4. Open `release_vX.Y.Z` into `main` and merge it with a merge commit. +5. Tag and publish from the resulting `main` commit. +6. Merge the release branch back into `develop` after the release passes regression. +7. Retain the release branch permanently as the release snapshot. + +Release branches must use the `release_*` pattern. Never open `develop` directly into `main`. + +## Hotfix branches + +For an urgent production fix: + +1. Create `hotfix/` from `main`. +2. Open it into `main`, complete review and CI, and merge it with a merge commit. +3. Merge the same hotfix branch into `develop`. + +Retain the hotfix branch until both merges are complete. + +## Allowed pull request routes + +| Source | Target | Purpose | +| --- | --- | --- | +| Development branch | `develop` | Normal development | +| `release_*` | `main` | Stable release | +| `release_*` | `develop` | Mandatory release back-merge | +| `hotfix/*` | `main` | Production hotfix | +| `hotfix/*` | `develop` | Hotfix back-merge | + +The `source-and-target` workflow enforces these routes. diff --git a/CHANGELOG.md b/CHANGELOG.md index c3e2b9f7..2026fd33 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Changed + +- Adopted `develop` as the integration branch and retained `main` for stable releases. +- Added enforced pull request routes for development, release, and hotfix branches. +- Added automated pull request title and description validation. +- Added pull request CI for policy tests, formatting, linting, build, and unit tests. + ## [1.1.0] - 2026-08-25 ### Upgrade notes diff --git a/CLAUDE.md b/CLAUDE.md index a4cbba34..3eb450b3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,6 +42,15 @@ Each component has its own `CLAUDE.md` (where present) with build/test commands - **Mechanism registration**: `tron:0xcd8690dc` (exact match, higher priority) beats `tron:*` (wildcard, lower priority). - **Commit messages**: `(): ` — e.g. `fix(tron): preserve raw_data_hex in tron approvals`. +## Branch workflow + +- Start normal development, documentation, maintenance, and upstream-sync branches from `develop` + and open them back to `develop`. +- Treat `main` as stable release history. Only `release_*` and `hotfix/*` branches may target + `main`. +- Never open `develop` directly into `main`. +- Follow [BRANCHING.md](BRANCHING.md) for release back-merges, hotfixes, and branch retention. + ## AI-native development This repo uses a Claude-Code-native layout: rules, commands, and agents that let Claude (and other agents following the same conventions) contribute safely without reading every file first. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7041e921..667fcf8d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,9 +26,19 @@ By participating in this project, you agree to abide by our Code of Conduct. We - Fill in the required template (if available). - Do not include more than one fix/feature per pull request. +- Start normal work from `develop` and open the pull request back to `develop`. +- Use `release_*` or `hotfix/*` branches for pull requests to `main`; never merge `develop` + directly into `main`. - Ensure that the tests pass and the code adheres to the project's coding standards. - Update the documentation if you've made changes to the API or added new features. - Commit messages follow `(): ` (see [.claude/rules/common/conventions.md](.claude/rules/common/conventions.md)). +- PR titles must use `type(scope): description`, contain 10-72 characters, start the description + with a lowercase letter or number, and not end with a period. Allowed types are `feat`, `fix`, + `refactor`, `docs`, `style`, `test`, `chore`, `ci`, `perf`, `build`, and `revert`. +- The PR template's Description section must explain what and why in at least 20 characters. + +See [BRANCHING.md](BRANCHING.md) for the complete development, release, back-merge, and hotfix +workflow. --- @@ -36,7 +46,7 @@ By participating in this project, you agree to abide by our Code of Conduct. We ### Prerequisites -- **Node.js**: 20+ +- **Node.js**: 22+ - **pnpm**: >= 11 (workspace package manager) - **A wallet**: a TRON wallet with TRX (Nile/Shasta testnets) and/or a BSC wallet with BNB, for gas. diff --git a/README.md b/README.md index da945b71..f32e3a4d 100644 --- a/README.md +++ b/README.md @@ -201,7 +201,9 @@ Use `pnpm build:release` before `pnpm pack` or `pnpm publish`. The forced build ## Contributing -We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. +We welcome contributions! Start normal work from `develop` and submit it back to `develop`. +Stable releases reach `main` through a `release_*` branch. See [CONTRIBUTING.md](./CONTRIBUTING.md) +and [BRANCHING.md](./BRANCHING.md) for the complete workflow. ## License diff --git a/typescript/.changeset/config.json b/typescript/.changeset/config.json index b9f3de2b..6d38b29d 100644 --- a/typescript/.changeset/config.json +++ b/typescript/.changeset/config.json @@ -10,7 +10,7 @@ "fixed": [], "linked": [], "access": "public", - "baseBranch": "main", + "baseBranch": "develop", "updateInternalDependencies": "patch", "ignore": [] }