Fully Automate the Release Process of Fable using Release-Please

[dbrattli]

Proposal: Automated Releases for Fable using Release-Please

Motivation

Fable has several maintainers, with one primarily handles the release process. This works, but the release process is manual and time-consuming — requiring making sure CHANGELOGs are updated, coordinating version numbers across multiple files, and executing the publish steps locally.

This proposal explores how we could automate the release process to:

• Reduce workload for the maintainer currently handling releases
• Enable other maintainers to help with releases without needing knowledge of the process
• Speed up release velocity so contributors see their work published sooner, and users of Fable can get fixes earlier
• Remove manual steps everything handled automatically in GitHub actions

Proposed Solution

Adopt release-please to automate the release workflow. Release-please is a Google-maintained tool that:

1. Monitors commits on the main branch
2. Automatically creates/updates Release PRs with changelog entries and version bumps
3. When a Release PR is merged, triggers publishing workflows

How It Works

Contributor PR merged
        ↓
release-please sees conventional commits (feat:, fix:, etc.)
        ↓
Creates/updates a Release PR with:
  - Updated CHANGELOG.md
  - Bumped version in .fsproj files
  - Updated VERSION literal in Compiler.fs
        ↓
Maintainer reviews and merges Release PR
        ↓
GitHub Action publishes to NuGet automatically

The release process simplifies from "execute all the steps" to "review and merge a PR" — a much lighter task that any of the maintainers could handle.

Existing Automation: PyPI Publishing

Fable already has automated publishing for fable-library to PyPI via .github/workflows/publish-pypi.yml. This workflow:

• Triggers on release: types: [published] (GitHub Release creation)
• Derives version from git tags using dunamai
• Builds wheels for all platforms
• Publishes to PyPI automatically

This is already release-please compatible! Here's why:

1. release-please creates GitHub Releases when Release PRs are merged
2. GitHub Releases trigger the existing release: types: [published] event
3. The existing PyPI workflow would fire automatically — no changes needed
4. Version derivation from git tags works because release-please creates tags

This means adopting release-please for NuGet would also unify the release trigger for PyPI — one Release PR merge could trigger both NuGet and PyPI publishing (if the fable-library is part of that release).

This proposal extends that existing pattern to NuGet publishing, bringing the same automation to the .NET packages.

Fable-Specific Considerations

Independent Versioning of Packages

Fable releases Fable.Cli, Fable.Core, and Fable.Compiler independently with different version numbers. Release-please handles this through manifest mode with separate-pull-requests: true.

Controlled Major Versions

Fable maintains strict version discipline:

• v4.x.y is maintained for 1-2 years
• Breaking changes between major versions are considered bugs
• Major version transitions (v4 → v5) are deliberate decisions, not automatic

Release-please accommodates this:

• It only bumps major on feat!: or BREAKING CHANGE: commits — simply don't use these
• For intentional major bumps, use Release-As: 5.0.0-alpha.1 in a commit trailer
• Prerelease channels (alpha → beta → stable) are supported via configuration

Prerelease Workflow

v4.x.y stable
    ↓  (feat: commits → 4.minor.0, fix: commits → 4.x.patch)

Maintainer decides: time for v5
    ↓  (commit with "Release-As: 5.0.0-alpha.1")

v5.0.0-alpha.z development
    ↓  (feat:/fix: commits increment alpha.z)

Ready for beta
    ↓  (commit with "Release-As: 5.0.0-beta.1")

v5.0.0-beta.z stabilization
    ↓  (similar progression)

Stable release
    ↓  (commit with "Release-As: 5.0.0", update config)

Note on Release-As in monorepos: Release-please determines which component a commit affects based on which files the commit touches. To force a version for Fable.Cli, the commit must modify files under src/Fable.Cli/. For a coordinated bump across all components, touch files in each component's directory. The exact behavior of Release-As across multiple components should be verified during the testing phase.

Alternative for major transitions: You can also directly edit .release-please-manifest.json to set new base versions (e.g., change "4.24.0" to "5.0.0-alpha.0"), then the next feat: or fix: commit would increment from there.

Configuration Files

.github/workflows/release-please.yml

name: Release Please

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

This workflow only creates/updates Release PRs and creates GitHub Releases when merged. The actual publishing is triggered separately (see below).

.github/workflows/publish-nuget.yml

This follows the same pattern as the existing publish-pypi.yml:

name: Publish to NuGet

on:
  release:
    types: [published]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'
      
      - name: Determine package from release tag
        id: package
        run: |
          # Release tags from release-please look like: Fable.Cli-v4.25.0
          TAG="${{ github.event.release.tag_name }}"
          if [[ "$TAG" == Fable.Cli-* ]]; then
            echo "project=src/Fable.Cli/Fable.Cli.fsproj" >> $GITHUB_OUTPUT
          elif [[ "$TAG" == Fable.Core-* ]]; then
            echo "project=src/Fable.Core/Fable.Core.fsproj" >> $GITHUB_OUTPUT
          elif [[ "$TAG" == Fable.Compiler-* ]]; then
            echo "project=src/Fable.Compiler/Fable.Compiler.fsproj" >> $GITHUB_OUTPUT
          else
            echo "Unknown package tag: $TAG"
            exit 1
          fi
      
      - name: Pack
        run: dotnet pack ${{ steps.package.outputs.project }} -c Release
      
      - name: Publish to NuGet
        run: |
          dotnet nuget push **/*.nupkg \
            --api-key ${{ secrets.NUGET_API_KEY }} \
            --source https://api.nuget.org/v3/index.json \
            --skip-duplicate

This mirrors the PyPI workflow's approach:

• Triggers on GitHub Release (created by release-please)
• Can also be manually dispatched
• Determines which package from the release tag

release-please-config.json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "packages": {
    "src/Fable.Cli": {
      "release-type": "simple",
      "component": "Fable.Cli",
      "changelog-path": "CHANGELOG.md",
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": true,
      "extra-files": [
        {
          "type": "xml",
          "path": "Fable.Cli.fsproj",
          "xpath": "//Project/PropertyGroup/Version"
        }
      ]
    },
    "src/Fable.Core": {
      "release-type": "simple",
      "component": "Fable.Core",
      "changelog-path": "CHANGELOG.md",
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": true,
      "extra-files": [
        {
          "type": "xml",
          "path": "Fable.Core.fsproj",
          "xpath": "//Project/PropertyGroup/Version"
        }
      ]
    },
    "src/Fable.Compiler": {
      "release-type": "simple",
      "component": "Fable.Compiler",
      "changelog-path": "CHANGELOG.md",
      "bump-minor-pre-major": true,
      "bump-patch-for-minor-pre-major": true,
      "extra-files": [
        {
          "type": "xml",
          "path": "Fable.Compiler.fsproj",
          "xpath": "//Project/PropertyGroup/Version"
        }
      ]
    }
  },
  "separate-pull-requests": true,
  "sequential-calls": false,
  "changelog-sections": [
    {"type": "feat", "section": "Features"},
    {"type": "fix", "section": "Bug Fixes"},
    {"type": "perf", "section": "Performance Improvements"},
    {"type": "deps", "section": "Dependencies"},
    {"type": "docs", "section": "Documentation", "hidden": true},
    {"type": "chore", "section": "Miscellaneous", "hidden": true},
    {"type": "refactor", "section": "Code Refactoring", "hidden": true},
    {"type": "test", "section": "Tests", "hidden": true}
  ]
}

.release-please-manifest.json

This file tracks current versions. Initial setup (adjust to current actual versions):

{
  "src/Fable.Cli": "4.24.0",
  "src/Fable.Core": "4.5.0",
  "src/Fable.Compiler": "4.24.0"
}

Version Annotation in Compiler.fs

The VERSION literal in src/Fable.Transforms/Global/Compiler.fs needs to stay in sync with Fable.Cli. Add the annotation comment:

let [<Literal>] VERSION = "4.24.0" // x-release-please-version

And add to the Fable.Cli extra-files config:

"extra-files": [
  {
    "type": "xml",
    "path": "Fable.Cli.fsproj",
    "xpath": "//Project/PropertyGroup/Version"
  },
  {
    "type": "generic",
    "path": "../Fable.Transforms/Global/Compiler.fs"
  }
]

Conventional Commits

Contributors would need to use conventional commits:

feat(cli): add --sourceMaps flag for better debugging
fix(core): handle null in List.tryHead
fix(py): correct indentation in match expressions  
perf(compiler): cache type resolution results
docs(rs): update Rust target documentation

Scopes (optional but helpful):

• cli - Fable.Cli changes
• core - Fable.Core changes
• compiler - Fable.Compiler/Transforms changes
• js, ts, py, rs, dart - Language-specific changes
• lib - fable-library changes

Version bump rules:

• fix: → patch (4.24.0 → 4.24.1)
• feat: → minor (4.24.0 → 4.25.0)
• feat!: or BREAKING CHANGE: → major (but we avoid these between major releases)

Migration Plan

Phase 1: Setup (non-breaking)

1. Add release-please-config.json and .release-please-manifest.json
2. Add the GitHub workflow (disabled initially or on a test branch)
3. Add version annotation to Compiler.fs
4. Document the conventional commit format in CONTRIBUTING.md

Phase 2: Parallel Testing

1. Enable release-please on a feature branch
2. Make test commits to verify Release PRs generate correctly
3. Verify version bumps propagate to all required files
4. Test the NuGet publishing step with a dry-run

Phase 3: Gradual Adoption

1. Enable on main branch
2. Initially require manual approval for all Release PRs
3. Existing maintainers can still force versions via Release-As: when needed
4. Monitor and adjust configuration based on experience

Phase 4: Full Automation (optional)

1. Consider auto-merge for Release PRs if CI passes
2. This would enable fully hands-off releases

Trade-offs

What We Gain

• Reduced workload: Releases become "merge a PR" instead of a multi-step manual process
• Shared responsibility: Any of the maintainers can approve a release without special knowledge
• Faster release velocity: Contributors see their work shipped sooner
• Audit trail: Every release decision is a PR with discussion history
• Consistency: Version numbers, changelogs, and tags are always in sync

What We Lose / Change

• Hand-crafted changelogs: Auto-generated from commits (though you can edit the Release PR)
• Commit message discipline: Contributors need to follow conventional commits
• Flexibility: The process is more structured (though overrides exist)

Mitigation

• Release PRs can be edited before merging if changelog needs polish
• Commits can be squash-merged with a proper conventional commit message
• Release-As: provides escape hatch for any version override

Open Questions for Discussion

1. Changelog style: Are auto-generated changelogs acceptable, or do we value hand-crafted release notes enough to keep the current process?

2. Commit discipline: Is requiring conventional commits too much friction for occasional contributors? We can enforce this with e.g amannn/action-semantic-pull-request GH action.

3. Package scope: Should we include other packages like fable-metadata, fable-standalone, etc.?

4. Release responsibility: With automation in place, should all maintainers be comfortable merging Release PRs, or keep it with the current release maintainer?

References

• release-please documentation
• release-please-action
• Conventional Commits
• Manifest mode (monorepo) documentation
• Customizing Releases

[MangelMaxime]

Hello,

I am not against automated release this is why for example I created the EasyBuild ecosystem.

• Reduce workload for the maintainer currently handling releases

The manual action needed is not too big thanks to the existing automation we have in place. Here is what I am currently doing:

1. Pull the latest version of main

2. Update src/Fable.Cli/CHANGELOG.md with the new version and date

3. Update src/fable-standalone/CHANGELOG.md with the new Fable version

4. Looks through all the CHANGELOG.md files, if a new version is needed and update them

   I am using the List of changelogs section in the main CHANGELOG.md to help navigate through them quickly.

5. Run ./build.sh github-release

Note

These steps consider that you already have the Env variables configured, logged into NPM on your machine and authenticated in the gh CLI

Fable releases Fable.Cli, Fable.Core, and Fable.Compiler independently with different version numbers. Release-please handles this through manifest mode with separate-pull-requests: true.

If I understand correctly we would get 1 PRs per project? I think I would prefer to have a single PR to release all at once like done today.

This would require less work and also make sure we keep the packages in sync.

Plus, we also want to create a Github release (to trigger Pypy) only for Fable.CLI version (I think this is configurable in release-please manifest).

Document the conventional commit format in CONTRIBUTING.md

We can based this work on https://github.com/easybuild-org/EasyBuild.CommitParser#commit-format (need to remove the special Tag) from the documentation

Phase 4: Full Automation (optional)

I think I would hold on doing that, so we can release features in batch when needed. If we just need to Click merge to make a release it should be good enough for some time now.

1. **Changelog style**: Are auto-generated changelogs acceptable, or do we value hand-crafted release notes enough to keep the current process?

I am fine with using auto generated changelogs, to be honest right now most of our changelog is a copy/paste of the merge commit message already.

2. **Commit discipline**: Is requiring conventional commits too much friction for occasional contributors? We can enforce this with e.g `amannn/action-semantic-pull-request` GH action.

Based on my experience, this is the hardest part. It can be enforced to a certain limit using git hooks (via EasyBuild.CommitLinter but when doing the merge via Github UI we can't run hooks verification).

Hopefully, thanks to release-please creating PR, we can catch on issues regarding merged/squashed commits.

3. **Package scope**: Should we include other packages like `fable-metadata`, `fable-standalone`, etc.?

We should automate everything

4. **Release responsibility**: With automation in place, should all maintainers be comfortable merging Release PRs, or keep it with the current release maintainer?

I think for a starter we should probably keep me as the guy who press the red button. As if something is breaking, I can fix it.

But once, the workflow has been tested and we are comfortable with it we can extends the responsibility to others if they feel like it.

---

To move forward, what I propose is that I look into setting up release-phase. This is because, I would like to make sure to understand how it works. And this way, we would have at least two person (@dbrattli and me) in the team comfortable with it.

[dbrattli]

Looks like release-please will make a single PR for all packages that needs to be released. This can be controlled using the separate-pull-requests config option and is default false, i.e 1 PR: https://github.com/googleapis/release-please/blob/009c2a61a038843957e7002aa1c32e317b654aa1/docs/manifest-releaser.md?plain=1#L223

[dbrattli]

Based on my experience, this is the hardest part. It can be enforced to a certain limit using git hooks (via EasyBuild.CommitLinter but when doing the merge via Github UI we can't run hooks verification).

This can be enforced with a GH action: https://github.com/fable-compiler/Fable.Python/blob/main/.github/workflows/conventional-pr-title.yml