AACWorkflow Docs

Агент примечаний к выпуску

Автоматически собирайте объединенные PR и проблемы, курируйте примечания к выпуску с надлежащей категоризацией и черновики Changelog, готовые к отправке.

При каждом выпуске вам нужно рассказать пользователям, что изменилось. Это означает чтение объединенных PR, их категоризацию (функции, исправления, безопасность, внутренние), написание удобных для пользователя резюме и упаковку всего этого в примечания к выпуску.

Агент примечаний к выпуску автоматизирует этот рабочий процесс. Он собирает коммиты и PR с момента последнего выпуска, группирует их по типам и создает полированный черновик для вашего рассмотрения.

Что делает агент

При срабатывании (по требованию или перед выпуском) агент выпуска:

  1. Собирает коммиты — перечисляет все объединенные PR с момента последнего git-тега или выпуска
  2. Категоризирует изменения — сортирует PR в Features, Fixes, Security, Internal, Docs на основе ярлыков и сообщений о коммитах
  3. Пишет резюме — преобразует описания PR в краткие, удобные для пользователя пункты
  4. Выделяет критические изменения — отмечает основные версии или изменения API, требующие миграции
  5. Создает черновик Changelog — форматирует выпуск как ## [v1.2.0] - 2025-06-22 со всеми разделами
  6. Открывает PR — фиксирует черновик в CHANGELOG.md и docs/releases/v1.2.0.md, готовый для финальной проверки

Настройка

Предварительные условия

  • Рабочая область AACWorkflow с активным агентом
  • Git репозиторий с помеченными выпусками (или CHANGELOG.md)
  • GitHub интеграция настроена
  • PR последовательно помечены (например, type:feature, type:fix, type:security)

Шаг 1: Создание агента примечаний к выпуску

  1. Перейдите в Settings → Agents и нажмите New Agent
  2. Выберите ваш runtime и провайдер
  3. Назовите его release-notes или changelog-bot
  4. Добавьте эту системную подсказку:
Role: Release notes curator
Task: When assigned a "Prepare Release" task:
1. Find the last git tag (e.g., v1.2.0)
2. List all merged PRs since that tag
3. For each PR:
   - Extract title and author
   - Check labels (type:feature, type:fix, type:security, type:docs, type:chore)
   - Read description for context
   - Flag if it's a breaking change
4. Categorize into sections:
   - 🎉 Features (type:feature)
   - 🐛 Bug Fixes (type:fix)
   - 🔒 Security (type:security)
   - 📚 Documentation (type:docs)
   - 🔧 Internal / Chores (type:chore) — optional, show if significant
5. Write 1-2 line summary per PR (user perspective, not technical jargon)
6. Highlight migration guide if breaking changes exist
7. Include contributor credits
8. Create branch "release/v<VERSION>" and PR with:
   - Updated CHANGELOG.md (prepend new release)
   - New file docs/releases/v<VERSION>.md (full details)
9. Add PR to AACWorkflow for team review before merge

Output format:
## [1.2.0] - 2025-06-22

### Features
- **Workspace invites** — invite team members via email link (via @anna-dev in #123)
- **Custom agent skills** — attach reusable workflows to agents (via @devops-team in #456)

### Bug Fixes
- Fixed pagination token expiry causing 401 errors (via @alice in #789)
- Corrected timestamp display in non-UTC timezones (via @bob in #890)

### Security
- **CVE-2025-1234 (High)** — Patched request validation bypass in agent API (via @security-team in #1001)

### Breaking Changes ⚠️
- **Agent API v1 deprecated** — migrate to v2 by July 1st
  See [migration guide](/docs/api/v1-to-v2.md)

### Contributors
Thanks to @anna-dev, @devops-team, @alice, @bob, @security-team, and 3 more contributors.

Шаг 2: Требуйте ярлыки PR

Убедитесь, что ваш репозиторий требует ярлыки для всех PR. Добавьте workflow GitHub Actions .github/workflows/require-pr-label.yml:

name: Require PR Label
on: pull_request
jobs:
  check-labels:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v4
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Verify label applied
        if: ${{ !contains(github.event.pull_request.labels.*.name, 'type:*') }}
        run: |
          echo "❌ PR must have a 'type:' label"
          exit 1

Шаг 3: Триггер по требованию или запланированно

По требованию: Перейдите в Settings → Releases и нажмите Prepare Release. Назначьте release-notes агенту, он пробуждается и начинает.

Запланировано (например, ежемесячно): Добавьте cron-задачу в AACWorkflow или GitHub:

# Первый понедельник каждого месяца в 9:00
0 9 * * 1 [ $(date +%d) -le 7 ] && \
  curl -X POST https://aacworkflow.com/api/tasks \
    -H "Authorization: Bearer $TOKEN" \
    -d '{"agent_id": "release-notes", "title": "Prepare monthly release"}'

Шаг 4: Настройка правил выпуска

Добавьте .aacworkflow/release-config.yml:

release_notes:
  # Git tag pattern for finding last release
  tag_pattern: "v*"
  
  # Sections to include (in order)
  sections:
    - title: "🎉 Features"
      labels: ["type:feature"]
      hide_if_empty: false
    
    - title: "🐛 Bug Fixes"
      labels: ["type:fix"]
      hide_if_empty: false
    
    - title: "🔒 Security"
      labels: ["type:security"]
      hide_if_empty: true
    
    - title: "📚 Documentation"
      labels: ["type:docs"]
      hide_if_empty: true
    
    - title: "🔧 Internal"
      labels: ["type:chore"]
      hide_if_empty: true
  
  # Breaking changes
  breaking_changes_label: "breaking-change"
  breaking_changes_section: true
  
  # Include contributor credits
  include_contributors: true
  
  # Output files
  output_files:
    - CHANGELOG.md
    - docs/releases/v{VERSION}.md

Пример выходных примечаний к выпуску

PR title: docs: release notes for v1.2.0

Body:

## Release Summary

**v1.2.0** — June 22, 2025

📊 **Stats:** 23 PRs merged, 12 features, 8 fixes, 3 security patches, 15 contributors

---

## 🎉 Features

- **Workspace invites** — Send email invitations to teammates; they auto-join when they click. (PR #1234)
- **Custom agent skills** — Bundle reusable workflows as skills and attach to agents. (PR #1235)
- **Workspace audit log** — Track all team activity in Settings → Audit Log. (PR #1236)

## 🐛 Bug Fixes

- Fixed agent runtime not reconnecting after network drop
- Corrected issue timestamp display in non-UTC timezones
- Pagination tokens no longer expire prematurely
- Agent comments now show in correct order (newest first)

## 🔒 Security

- **CVE-2025-1234 (High)** — Patched request validation bypass in the Agent API. All users should upgrade.
- Fixed CSRF token rotation on login.

## ⚠️ Breaking Changes

**Agent API v1 is now deprecated.** Migrate to v2 by July 1st.
[See migration guide →](/docs/agents/api-migration.md)

## Contributors

Thanks to @anna-dev, @alice, @bob, @charlie, @devops-team, @security-team, and 9 more contributors for making v1.2.0 possible.

---

**Next step:** Review the release notes above. This PR updates `CHANGELOG.md` and creates `docs/releases/v1.2.0.md`.

Merge when ready, then run `git tag v1.2.0 && git push --tags` to publish the release.

Советы и лучшие практики

Помечайте каждый PR. Примечания к выпуску настолько хороши, насколько хорошо ваши ярлыки PR. Сделайте маркировку привычкой.

  • Черновик перед маркировкой — подготовьте примечания к выпуску ДО того, как вы пометите выпуск, чтобы они были готовы к отправке
  • Выделение критических изменений — используйте emoji ⚠️ и четкие инструкции миграции для любых критических изменений
  • Язык, ориентированный на пользователя — пишите с точки зрения пользователя, а не технического жаргона («Приглашения теперь работают автоматически», а не «Реализован асинхронный рабочий процесс приглашения»)
  • Благодарите участников — признавайте всех; это повышает боевой дух и сообщество
  • Ссылка на документы — ссылайтесь на связанные документы, руководства миграции и инструкции по обновлению в примечаниях к выпуску
  • Публикуйте на нескольких каналах — скопируйте примечания к выпуску в GitHub Releases, Slack, Twitter, ваш блог

Связанные руководства

  • Docs Maintenance Agent — поддерживайте документацию в синхронизации с выпусками
  • Dependency Update Agent — отслеживайте критические изменения в ваших зависимостях