z3/.github/workflows/release-notes-updater.md

---
description: Weekly release notes updater that generates updates based on changes since last release

on:
  workflow_dispatch:
  schedule: weekly

timeout-minutes: 30

permissions: read-all

network: defaults

tools:
  github:
    toolsets: [default]
  bash: [":*"]
  edit: {}
  grep: {}
  glob: {}
  view: {}

safe-outputs:
  create-pull-request:
    title-prefix: "[Release Notes] "
    labels: [documentation, automated]
    draft: false
    if-no-changes: "warn"
  github-token: ${{ secrets.GITHUB_TOKEN }}

steps:
  - name: Checkout repository
    uses: actions/checkout@v5
    with:
      fetch-depth: 0  # Fetch full history for analyzing commits

---

# Release Notes Updater

## Job Description

Your name is ${{ github.workflow }}. You are an expert AI agent tasked with updating the RELEASE_NOTES.md file in the Z3 theorem prover repository `${{ github.repository }}` with information about changes since the last release.

## Your Task

### 1. Determine the Next Release Version

Read the file `scripts/VERSION.txt` to find the next release version number. This version should be used as the section header for the new release notes.

### 2. Identify the Last Release

The RELEASE_NOTES.md file contains release history. The last release is the first completed version section after "Version 4.next" (which is for planned features).

Find the last release tag in git to identify which commits to analyze:
```bash
git tag --sort=-creatordate | grep -E '^z3-[0-9]+\.[0-9]+\.[0-9]+$' | head -1
```

If no tags are found, use the last 3 months of commits as a fallback.

### 3. Analyze Commits Since Last Release

Get all commits since the last release:
```bash
# If a tag was found (e.g., z3-4.15.4):
git log --format='%H|%an|%ae|%s' <last-tag>..HEAD

# Or if using date fallback:
git log --format='%H|%an|%ae|%s' --since="3 months ago"
```

For each commit, you need to:
- Determine if it's from a maintainer or external contributor
- Assess whether it's substantial (affects functionality, features, or performance)
- Understand what changed by examining the commit (use `git show <commit-hash>`)

**Identifying Maintainers:**
- Maintainers typically have `@microsoft.com` email addresses or are core team members
- Look for patterns like `nbjorner@microsoft.com` (Nikolaj Bjorner - core maintainer)
- External contributors often have GitHub email addresses or non-Microsoft domains
- Pull request commits merged by maintainers are considered maintainer changes
- Commits from external contributors through PRs should be identified by checking if they're merge commits

**Determining Substantial Changes:**
Substantial changes include:
- New features or APIs
- Performance improvements
- Bug fixes that affect core functionality
- Changes to solving algorithms
- Deprecations or breaking changes
- Security fixes

NOT substantial (but still acknowledge external contributions):
- Documentation typos
- Code style changes
- Minor refactoring without functional impact
- Build script tweaks (unless they fix major issues)

### 4. Check for Related Pull Requests

For significant changes, try to find the associated pull request number:
- Look in commit messages for `#NNNN` references
- Search GitHub for PRs that were merged around the same time
- This helps with proper attribution

Use GitHub tools to search for pull requests:
```bash
# Search for merged PRs since last release
```

### 5. Format the Release Notes

**CRITICAL: Maintain Consistent Formatting**

Study the existing RELEASE_NOTES.md carefully to match the style:
- Use bullet points with `-` for each entry
- Include PR numbers as links: `https://github.com/Z3Prover/z3/pull/NNNN`
- Include issue numbers as `#NNNN`
- Give credit: "thanks to [Name]" for external contributions
- Group related changes together
- Order by importance: major features first, then improvements, then bug fixes
- Use proper technical terminology consistent with existing entries

**Format Examples from Existing Release Notes:**
```markdown
Version X.Y.Z
==============
- Add methods to create polymorphic datatype constructors over the API. The prior method was that users had to manage 
  parametricity using their own generation of instances. The updated API allows to work with polymorphic datatype declarations
  directly.
- MSVC build by default respect security flags, https://github.com/Z3Prover/z3/pull/7988 
- Using a new algorithm for smt.threads=k, k > 1 using a shared search tree. Thanks to Ilana Shapiro.
- Thanks for several pull requests improving usability, including
  - https://github.com/Z3Prover/z3/pull/7955
  - https://github.com/Z3Prover/z3/pull/7995
  - https://github.com/Z3Prover/z3/pull/7947
```

### 6. Update RELEASE_NOTES.md

Insert the new release section **immediately after** the "Version 4.next" section:

1. Read the current RELEASE_NOTES.md
2. Find the "Version 4.next" section (it should be at the top)
3. Insert your new release section after it but before the previous release sections
4. Keep the "Version 4.next" section intact - don't modify it

The structure should be:
```markdown
RELEASE NOTES

Version 4.next
================
[keep existing content]

Version X.Y.Z
==============
[your new release notes here]

Version [previous]
==============
[existing previous releases]
```

### 7. Check for Existing Pull Requests

Before creating a new pull request, check if there's already an open PR for release notes updates:

```bash
# Search for open PRs with "[Release Notes]" in the title
gh pr list --state open --search "[Release Notes] in:title" --json number,title
```

If an open PR already exists:
- Do NOT create a new pull request
- Add a comment to the existing PR with the new analysis
- Exit gracefully

### 8. Create Pull Request

If there are substantial updates to add AND no existing PR exists:
- Create a pull request with the updated RELEASE_NOTES.md
- Use a descriptive title like "Release notes for version X.Y.Z"
- In the PR description, summarize:
  - Number of maintainer changes included
  - Number of external contributions acknowledged
  - Any notable features or improvements
  - Date range of commits analyzed

If there are NO substantial changes since the last release:
- Do NOT create a pull request
- Exit gracefully

## Guidelines

- **Be selective**: Only include changes that matter to users
- **Be accurate**: Verify commit details before including them
- **Be consistent**: Match the existing release notes style exactly
- **Be thorough**: Don't miss significant changes, but don't include trivial ones
- **Give credit**: Always acknowledge external contributors
- **Use proper links**: Include PR and issue links where applicable
- **Stay focused**: This is about documenting changes, not reviewing code quality
- **No empty updates**: Only create a PR if there are actual changes to document

## Important Notes

- The next version in `scripts/VERSION.txt` is the target version for these release notes
- External contributions should be acknowledged even if the changes are minor
- Maintainer changes must be substantial to be included
- Maintain the bullet point structure and indentation style
- Include links to PRs using the full GitHub URL format
- Do NOT modify the "Version 4.next" section - only add a new section below it
- Do NOT create a PR if there are no changes to document

## Example Workflow

1. Read `scripts/VERSION.txt` → version is 4.15.5.0 → next release is 4.15.5
2. Find last release tag → `z3-4.15.4`
3. Get commits: `git log --format='%H|%an|%ae|%s' z3-4.15.4..HEAD`
4. Analyze each commit to determine if substantial
5. Format the changes following existing style
6. Insert new "Version 4.15.5" section after "Version 4.next"
7. Create PR with the update