From a97f3aefa0c0b77b99f34c83b6727e45bff36a27 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Fri, 28 Aug 2026 21:01:02 +0800 Subject: [PATCH 1/4] ci: adopt develop and release branch workflow --- .github/pull_request_template.md | 21 +++++++ .github/workflows/audit-pr.yml | 1 + .github/workflows/branch-policy.yml | 19 ++++++ AGENTS.md | 12 ++-- BRANCHING.md | 86 ++++++++++++++++++++++++++ CHANGELOG.md | 8 +++ CONTRIBUTING.md | 95 +++++++++++++++++++---------- README.md | 12 +++- scripts/check_branch_policy.sh | 39 ++++++++++++ 9 files changed, 255 insertions(+), 38 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/branch-policy.yml create mode 100644 BRANCHING.md create mode 100644 scripts/check_branch_policy.sh diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..47d8b80 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,21 @@ +## Summary + +Describe what changed and why. + +## Branch routing + +- [ ] Ordinary work targets `develop` from `feature/*`. +- [ ] A `main` PR comes only from `release_*` or `hotfix/*`. +- [ ] Release and hotfix changes will also be merged into `develop`. + +## Skill checks + +- [ ] Changed `SKILL.md` files have valid YAML frontmatter. +- [ ] Dependencies and supported versions are documented consistently. +- [ ] Examples, resources, JSON files, and scripts were validated where applicable. +- [ ] Security, confirmation, secret-handling, network, and fee implications were reviewed. +- [ ] README and changelog entries were updated when behavior or the public catalog changed. + +## Verification + +List the commands or agent scenarios used to verify the change. diff --git a/.github/workflows/audit-pr.yml b/.github/workflows/audit-pr.yml index 9bc2141..743cd30 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 0000000..accff82 --- /dev/null +++ b/.github/workflows/branch-policy.yml @@ -0,0 +1,19 @@ +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 + - name: Validate pull request route + run: sh scripts/check_branch_policy.sh "${{ github.base_ref }}" "${{ github.head_ref }}" diff --git a/AGENTS.md b/AGENTS.md index 11b1db7..f97dd4a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -305,12 +305,15 @@ Always include: ### Contribution Workflow -1. **Create skill directory** under `skills/` -2. **Write SKILL.md** following the format -3. **Add examples** in `examples/` +1. **Synchronize `develop`** with the upstream repository +2. **Create `feature/`** from `develop` +3. **Create or update the Skill** following this guide 4. **Test thoroughly** with AI agents 5. **Document dependencies** clearly -6. **Submit for review** +6. **Submit a pull request to `develop`** + +Do not push directly to `develop` or `main`. Release and hotfix work follows +[BRANCHING.md](./BRANCHING.md). ### Review Criteria @@ -327,6 +330,7 @@ Always include: | Resource | Description | |----------|-------------| +| [BRANCHING.md](./BRANCHING.md) | Development, release, and hotfix workflow | | [mcp-server-tron](../mcp-server-tron/) | TRON blockchain MCP server | | [DEVELOPER_GUIDE.md](../DEVELOPER_GUIDE.md) | Project-wide development guide | | [agents.md](../agents.md) | Agent architecture documentation | diff --git a/BRANCHING.md b/BRANCHING.md new file mode 100644 index 0000000..70aa00e --- /dev/null +++ b/BRANCHING.md @@ -0,0 +1,86 @@ +# Branching and Release Workflow + +This repository follows the java-tron branching model while retaining `main` as the name of the +stable release branch. + +## Key branches + +| Branch | Purpose | +|---|---| +| `develop` | Default development and integration branch for the next release | +| `main` | Stable branch containing only released Skills collections | +| `release_vX.Y.Z` | Release snapshot cut from `develop`, regression-tested, and permanently retained | +| `feature/*` | Feature, fix, documentation, test, refactor, or CI work cut from `develop` | +| `hotfix/*` | Urgent fix cut from `main` for an already released version | + +Direct pushes to `develop` and `main` are not allowed. Changes enter both branches through reviewed +pull requests. + +## Development flow + +1. Synchronize a local `develop` branch with `upstream/develop`. +2. Create `feature/` from `develop`. +3. Submit the pull request to `develop`. +4. After review and required checks pass, merge it into `develop`. + +Use `feature/*` for every ordinary change. The commit and pull-request type still communicates +whether the work is a feature, fix, documentation update, refactor, test, build, or CI change. + +## Release flow + +1. Create `release_vX.Y.Z` from `develop` when the release scope is frozen. +2. Update the repository and Skill versions, changelog, dependency pins, and release notes there. +3. Run regression, installation, and agent-behavior tests on the release branch. +4. Merge release-blocking fixes directly into `release_vX.Y.Z`; do not add unrelated features. +5. After regression passes, merge `release_vX.Y.Z` into `main` and tag the merge commit `vX.Y.Z`. +6. Merge `release_vX.Y.Z` back into `develop` so every release fix is preserved. +7. Permanently retain the release branch as the source snapshot for that release. + +## Hotfix flow + +1. Create `hotfix/` from `main`. +2. Limit the branch to the released defect and its tests or documentation. +3. Merge the hotfix into `main` and create the corresponding patch release tag. +4. Merge the same hotfix into `develop`. + +## Pull-request routing + +| Target | Allowed source branches | +|---|---| +| `develop` | `feature/*`, `release_*`, `hotfix/*` | +| `main` | `release_*`, `hotfix/*` | + +The `release_*` and `hotfix/*` routes back to `develop` are mandatory. A feature branch must never +target `main` directly. + +## Installation channels + +Because `develop` is the development branch, public installation instructions must select a stable +source explicitly: + +```bash +npx skills add https://github.com/BofAI/skills/tree/main +``` + +Use the development branch only for intentional pre-release testing: + +```bash +npx skills add https://github.com/BofAI/skills/tree/develop +``` + +For reproducible production installation, prefer a formal version tag when one is available: + +```bash +npx skills add https://github.com/BofAI/skills/tree/vX.Y.Z +``` + +## Required repository settings + +Configure GitHub after the bootstrap pull request lands: + +- make `develop` the default branch; +- protect `develop` and `main` from direct and force pushes; +- require pull requests, at least one approval, and all required checks; +- require conversation resolution; +- restrict deletion of both long-lived branches; +- allow `main` pull requests only from `release_*` and `hotfix/*` through the branch-policy check. diff --git a/CHANGELOG.md b/CHANGELOG.md index 933dc86..509dc20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [Unreleased] + +### Improvements + +- Added the `develop`, `main`, `release_*`, `feature/*`, and `hotfix/*` branch workflow. +- Added pull-request branch routing checks and a repository pull-request template. +- Pinned stable installation documentation to the `main` branch. + ## [1.5.9] - 2026-07-09 ### Improvements diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a1c4bf7..43b3aae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,55 +1,86 @@ -# Contributing to Skills Repository +# Contributing to BofAI Skills -Thank you for your interest in contributing to the Skills Repository! +Thank you for contributing. Read [AGENTS.md](./AGENTS.md) for Skill authoring requirements and +[BRANCHING.md](./BRANCHING.md) for the repository's branch and release model. -## How to Contribute +## Key branches -### 1. Fork and Clone +- `develop` is the default development and integration branch. +- `main` contains stable, released Skills collections. +- `release_*` branches are release snapshots created from `develop` and merged into `main` after + regression testing. +- `feature/*` branches contain ordinary work created from `develop`. +- `hotfix/*` branches contain urgent released-version fixes created from `main`. + +Do not push directly to `develop` or `main`. + +## Fork and clone + +Fork `BofAI/skills`, then configure the official repository as `upstream`: ```bash -git fork https://github.com/open-aibank/skills-tron -git clone https://github.com/your-username/skills-tron -cd skills-tron +git clone https://github.com//skills.git +cd skills +git remote add upstream https://github.com/BofAI/skills.git ``` -### 2. Create a New Skill +## Synchronize and develop + +Synchronize your fork's development branch: + +```bash +git fetch upstream +git switch develop +git merge upstream/develop --no-ff +git push origin develop +``` -Follow the [AGENTS.md](AGENTS.md) guide to create your skill: +Create an ordinary work branch from `develop`: ```bash -mkdir -p my-skill/{examples,resources,scripts} +git switch -c feature/ develop ``` -### 3. Test Your Skill +Use the `feature/*` prefix for features, fixes, documentation, tests, refactors, build changes, and +CI changes. Describe the change type in the commit and pull-request title. + +## Validate the change + +- Ensure every changed `SKILL.md` has valid YAML frontmatter. +- Test the Skill with realistic agent requests. +- Verify examples and scripts work as documented. +- Validate JSON and other resource files. +- Document exact external CLI versions when deterministic behavior matters. +- Review security, secrets, confirmation, network, slippage, and fee behavior. -- Ensure SKILL.md has valid YAML frontmatter -- Test with an AI agent -- Verify all examples work -- Check JSON files are valid +Follow any repository validation commands documented in `AGENTS.md` or the affected Skill. -### 4. Submit Pull Request +## Submit a pull request -- Create a descriptive PR title -- Explain what the skill does -- Include testing instructions -- Reference any related issues +Push the branch to your fork and open a pull request targeting `develop`: -## Skill Quality Guidelines +```bash +git push origin feature/ +``` -- ✅ Clear, step-by-step instructions -- ✅ Complete examples -- ✅ Proper error handling -- ✅ Security considerations documented -- ✅ All dependencies listed +The title must use Conventional Commits, for example: -## Code of Conduct +```text +feat(wallet-cli): add resource delegation guidance +fix(sunswap): validate the configured network +docs: clarify stable installation +``` -Be respectful and constructive in all interactions. +Keep one pull request focused on one concern. Explain what changed, why it changed, and how it was +verified. Address review feedback and keep the branch synchronized with `develop`. -## Questions? +## Release and hotfix contributions -Open an issue or reach out to maintainers. +Maintainers create `release_*` and `hotfix/*` branches. Release branches accept only release +preparation and regression fixes. Hotfix branches accept only urgent corrections for code already +published from `main`. Both must be merged back into `develop`. ---- +## Code of conduct -Thank you for contributing! 🎉 +Be respectful and constructive in all interactions. Open an issue when a substantial new workflow +needs design discussion before implementation. diff --git a/README.md b/README.md index 2eaea88..c9bb340 100644 --- a/README.md +++ b/README.md @@ -44,12 +44,20 @@ BANK OF AI Skills are reusable, task-oriented capabilities that teach AI agents ## Installation -Use the standard installer and follow the `npx` prompts to select the skills you want and the agentic platform you use. This installs the selected Skill definitions but does not install their external CLI dependencies. +Use the stable `main` branch and follow the `npx` prompts to select the skills you want and the agentic platform you use. This installs the selected Skill definitions but does not install their external CLI dependencies. ```bash -npx skills add https://github.com/BofAI/skills.git +npx skills add https://github.com/BofAI/skills/tree/main ``` +The default development branch may contain unreleased changes. Use it only for intentional testing: + +```bash +npx skills add https://github.com/BofAI/skills/tree/develop +``` + +See [BRANCHING.md](./BRANCHING.md) for the development, release, and hotfix workflow. + ### Agent Wallet (Required for Signing Skills) Some skills require wallet signature operations and are built on Agent Wallet. Before using those skills, follow the [Agent Wallet Quick Start](https://github.com/BofAI/agent-wallet?tab=readme-ov-file#quick-start) to configure your environment. diff --git a/scripts/check_branch_policy.sh b/scripts/check_branch_policy.sh new file mode 100644 index 0000000..cb18584 --- /dev/null +++ b/scripts/check_branch_policy.sh @@ -0,0 +1,39 @@ +#!/bin/sh +set -eu + +base_branch=${1:-${GITHUB_BASE_REF:-}} +head_branch=${2:-${GITHUB_HEAD_REF:-}} + +if [ -z "$base_branch" ] || [ -z "$head_branch" ]; then + printf 'usage: %s \n' "$0" >&2 + exit 2 +fi + +case "$base_branch" in + develop) + case "$head_branch" in + feature/*|release_*|hotfix/*) ;; + *) + printf 'PRs to develop must come from feature/*, release_*, or hotfix/*; got %s.\n' \ + "$head_branch" >&2 + exit 1 + ;; + esac + ;; + main) + case "$head_branch" in + release_*|hotfix/*) ;; + *) + printf 'PRs to main must come from release_* or hotfix/*; got %s.\n' \ + "$head_branch" >&2 + exit 1 + ;; + esac + ;; + *) + printf 'Unsupported target branch: %s.\n' "$base_branch" >&2 + exit 1 + ;; +esac + +printf 'Allowed PR route: %s -> %s.\n' "$head_branch" "$base_branch" From 9a310d2c074431ac8997a69077638394684af0fa Mon Sep 17 00:00:00 2001 From: roger-gan Date: Sat, 29 Aug 2026 07:30:01 +0800 Subject: [PATCH 2/4] fix(ci): secure pull request audit workflow --- .github/workflows/audit-pr.yml | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/.github/workflows/audit-pr.yml b/.github/workflows/audit-pr.yml index 743cd30..f082147 100644 --- a/.github/workflows/audit-pr.yml +++ b/.github/workflows/audit-pr.yml @@ -22,7 +22,9 @@ concurrency: jobs: audit-on-pr: name: Audit on pull request - if: github.event_name == 'pull_request' + if: > + github.event_name == 'pull_request' && + github.event.pull_request.head.repo.full_name == github.repository runs-on: [self-hosted, Linux, ARM64, audit-linux] steps: @@ -34,6 +36,7 @@ jobs: - name: Check required tools run: | + which git which zip which jq which python3 @@ -43,8 +46,13 @@ jobs: shell: bash run: | ARCHIVE_NAME="${{ github.event.repository.name }}.zip" + if git ls-files -s | awk '$1 == "120000" { found=1 } END { exit !found }'; then + echo "Refusing to archive tracked symbolic links" + exit 1 + fi rm -f "/tmp/${ARCHIVE_NAME}" - zip -r "/tmp/${ARCHIVE_NAME}" . + git ls-files -z | xargs -0 -r zip -q "/tmp/${ARCHIVE_NAME}" -- + test -s "/tmp/${ARCHIVE_NAME}" echo "archive_name=${ARCHIVE_NAME}" >> "$GITHUB_OUTPUT" - name: Submit audit job @@ -188,6 +196,7 @@ jobs: - name: Check required tools run: | + which git which zip which jq which python3 @@ -197,8 +206,13 @@ jobs: shell: bash run: | ARCHIVE_NAME="${{ github.event.repository.name }}.zip" + if git ls-files -s | awk '$1 == "120000" { found=1 } END { exit !found }'; then + echo "Refusing to archive tracked symbolic links" + exit 1 + fi rm -f "/tmp/${ARCHIVE_NAME}" - zip -r "/tmp/${ARCHIVE_NAME}" . + git ls-files -z | xargs -0 -r zip -q "/tmp/${ARCHIVE_NAME}" -- + test -s "/tmp/${ARCHIVE_NAME}" echo "archive_name=${ARCHIVE_NAME}" >> "$GITHUB_OUTPUT" - name: Submit audit job From edc2aef27e02ed05ca93d67a37be2ffdf47c20f9 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Sat, 29 Aug 2026 07:41:23 +0800 Subject: [PATCH 3/4] ci: temporarily disable automatic audits --- .github/workflows/audit-pr.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/audit-pr.yml b/.github/workflows/audit-pr.yml index f082147..d154d5a 100644 --- a/.github/workflows/audit-pr.yml +++ b/.github/workflows/audit-pr.yml @@ -22,8 +22,11 @@ concurrency: jobs: audit-on-pr: name: Audit on pull request + # Disabled by default while the self-hosted audit runner is unavailable. + # Set the repository variable AUDIT_AUTO_ENABLED=true to restore automatic audits. if: > github.event_name == 'pull_request' && + vars.AUDIT_AUTO_ENABLED == 'true' && github.event.pull_request.head.repo.full_name == github.repository runs-on: [self-hosted, Linux, ARM64, audit-linux] From 977996ef5120c80b0e4ed6bd29b5aa12e610cab5 Mon Sep 17 00:00:00 2001 From: roger-gan Date: Sat, 29 Aug 2026 07:45:45 +0800 Subject: [PATCH 4/4] fix(ci): satisfy audit check while disabled --- .github/workflows/audit-pr.yml | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/.github/workflows/audit-pr.yml b/.github/workflows/audit-pr.yml index d154d5a..4809d4c 100644 --- a/.github/workflows/audit-pr.yml +++ b/.github/workflows/audit-pr.yml @@ -24,20 +24,25 @@ jobs: name: Audit on pull request # Disabled by default while the self-hosted audit runner is unavailable. # Set the repository variable AUDIT_AUTO_ENABLED=true to restore automatic audits. - if: > - github.event_name == 'pull_request' && - vars.AUDIT_AUTO_ENABLED == 'true' && - github.event.pull_request.head.repo.full_name == github.repository - runs-on: [self-hosted, Linux, ARM64, audit-linux] + if: github.event_name == 'pull_request' + runs-on: ${{ fromJSON(vars.AUDIT_AUTO_ENABLED == 'true' && github.event.pull_request.head.repo.full_name == github.repository && '["self-hosted","Linux","ARM64","audit-linux"]' || '["ubuntu-latest"]') }} + env: + AUTO_AUDIT_ENABLED: ${{ vars.AUDIT_AUTO_ENABLED == 'true' && github.event.pull_request.head.repo.full_name == github.repository }} steps: + - name: Automatic audit disabled + if: env.AUTO_AUDIT_ENABLED != 'true' + run: echo "Automatic audit is disabled" + - name: Checkout PR head + if: env.AUTO_AUDIT_ENABLED == 'true' uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 - name: Check required tools + if: env.AUTO_AUDIT_ENABLED == 'true' run: | which git which zip @@ -45,6 +50,7 @@ jobs: which python3 - name: Create source archive + if: env.AUTO_AUDIT_ENABLED == 'true' id: archive shell: bash run: | @@ -59,6 +65,7 @@ jobs: echo "archive_name=${ARCHIVE_NAME}" >> "$GITHUB_OUTPUT" - name: Submit audit job + if: env.AUTO_AUDIT_ENABLED == 'true' id: submit shell: bash run: | @@ -81,6 +88,7 @@ jobs: echo "report_url=$REPORT_URL" >> "$GITHUB_OUTPUT" - name: Poll report until ready + if: env.AUTO_AUDIT_ENABLED == 'true' id: poll shell: bash run: | @@ -108,6 +116,7 @@ jobs: exit 1 - name: Fetch markdown report + if: env.AUTO_AUDIT_ENABLED == 'true' shell: bash run: | REPORT_PATH="${{ steps.submit.outputs.report_url }}" @@ -123,6 +132,7 @@ jobs: fi - name: Normalize markdown for GitHub comment + if: env.AUTO_AUDIT_ENABLED == 'true' shell: bash run: | python3 <<'PY' @@ -140,6 +150,7 @@ jobs: PY - name: Comment markdown report to PR + if: env.AUTO_AUDIT_ENABLED == 'true' uses: actions/github-script@v7 with: script: |