toys-release 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f2bad43c37b4109aee66b380e4e0e6497a390d4d7411727ded7b6fb583f2655
+  data.tar.gz: e9a297a316744b9523bab8976a63b43a7f1728424572f561bc8bde3255cdb932
+SHA512:
+  metadata.gz: feee3189f4e0fb77d08c506aefb2130b8a00f46ac53066c5407fd1f2200ed8264acff74ec90facf2ec29e5b2b04e37e908421459528c1d08b486af4ef3b8a597
+  data.tar.gz: a07912d6c512bf037d71b7394b007af8d918cc9eafb518ef3a5779642c35462c21115ea57e48604c6a3653f59a1781bdaca77321199bcd4dfa1101dc396ba8f5

data/.yardopts

@@ -0,0 +1,11 @@
+--no-private
+--title=Toys Release System
+--markup=markdown
+--markup-provider redcarpet
+--main=README.md
+./lib/**/*.rb
+-
+README.md
+LICENSE.md
+CHANGELOG.md
+docs/guide.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release History
+
+### v0.1.0 / 2025-11-09
+
+Initial release of the toys-release gem

data/LICENSE.md

@@ -0,0 +1,21 @@
+# License
+
+Copyright 2025 Daniel Azuma and the Toys contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,87 @@
+# Toys-Release
+
+Toys-Release is a Ruby library release system built on GitHub Actions and the
+Toys gem. It interprets [conventional commit](https://conventionalcommits.org/)
+message format to automate changelog generation and library version updating
+based on semantic versioning, and supports fine tuning and approval of releases
+using GitHub pull requests.
+
+Out of the box, Toys-Release knows how to tag GitHub releases, build and push
+gems to Rubygems, and build and publish documentation to gh-pages. You can also
+customize the build pipeline and many aspects of its behavior.
+
+## Description
+
+Toys-Release is desigend to be installed on a GitHub repository. This
+installation consists of a set of GitHub Actions workflows, a configuration
+file, and a GitHub Actions secret for your RubyGems credentials.
+
+Once installed, Toys-Release provides command line tools and GitHub Actions
+workflows for performing and managing releases. These tools are built atop the
+Toys framework.
+
+### The Toys release process
+
+Releases using Toys-Release will generally look like the following.
+
+When you are ready to do a release, go to the GitHub Action tab on your
+repository and trigger the "Open Release Request" action. (Alternately, you can
+run this action on the command line.) This action analyzes your repository,
+finding changes that were committed since the last release. If those commit
+messages were formatted properly with Conventional Commit tags, the action will
+be able to generate a new entry in your changelog, and suggeset a proper
+version for the new release in line with Semantic Versioning. It will then open
+a pull request with the version update and changelog addition.
+
+You can then review this pull request and modify it if you want to alter the
+version to be released, or the changelog text. Once you are satisfied, merge
+the pull request. Toys-Release will then automatically perform the release,
+tagging it in GitHub and building and pushing a new Ruby gem release. It can
+also be configured to build your gem's documentation and push it to your
+repository's gh-pages branch for publication. You can cancel the release simply
+by closing the pull request without merging.
+
+### Key features
+
+* Tight integration with GitHub Actions provides a convenient workflow for
+  GitHub-based projects.
+* Automatically generates changelogs based on Conventional Commit messages.
+* Automatically proposes releases with semver-aligned version increments based
+  on the semantics implied by the commit messages.
+* Approve and adjust releases and changelogs by editing pull requests.
+* Automatic pre-release checks verify that CI passes and release status is
+  consistent.
+* Fix and retry failed releases via GitHub Actions or command line.
+* Supports single-library repositories and multi-library monorepos.
+* Support for groups of libraries that must be released together.
+* Support for publishing reference documentation to gh-pages.
+* Fine-grained configuration of the release pipeline.
+
+### System requirements
+
+Toys-Release requires Ruby 2.7 or later, and Toys 0.17 or later. We recommend
+the latest version of the standard C implementation of Ruby. (JRuby or
+TruffleRuby _may_ work, but are unsupported.) The Ruby provided by the standard
+setup-ruby GitHub Action is sufficient.
+
+## License
+
+Copyright 2019-2025 Daniel Azuma and the Toys contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/docs/guide.md

@@ -0,0 +1,7 @@
+<!--
+# @title Toys-Release User Guide
+-->
+
+# Toys-Release User Guide
+
+(To be written)

data/lib/toys/release/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Toys
+  module Release
+    ##
+    # Current version of the Toys release system.
+    # @return [String]
+    #
+    VERSION = "0.1.0"
+  end
+end

data/lib/toys-release.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+##
+# Toys is a configurable command line tool. Write commands in config files
+# using a simple DSL, and Toys will provide the command line executable and
+# take care of all the details such as argument parsing, online help, and error
+# reporting. Toys is designed for software developers, IT professionals, and
+# other power users who want to write and organize scripts to automate their
+# workflows. It can also be used as a Rake replacement, providing a more
+# natural command line interface for your project's build tasks.
+#
+module Toys
+  ##
+  # The Toys Release system is a set of conventional commits based release
+  # tools, distributed in a Rubygem. The functionality is not available via
+  # Ruby libraries. Instead use the Toys load_gem functionality to import the
+  # release tools into your project. See the readme and user guide for details.
+  #
+  module Release
+  end
+end
+
+require "toys/release/version"

data/toys/.data/templates/gh-pages-404.html.erb

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+  </head>
+  <body>
+    <p>
+      <a href="https://<%= @url_base %>/index.html">Main documentation page</a>
+    </p>
+  </body>
+  <script>
+<% @relevant_component_settings.map { |comp| comp.gh_pages_version_var }.uniq.each do |version_var| %>    var <%= version_var %> = "0.0.0";
+<% end %>    var location_updated = false;
+<% @relevant_component_settings.each do |component_settings| %>    if (!location_updated && window.location.href.includes("//<%= @url_base %>/<%= component_settings.gh_pages_directory %>/latest")) {
+      var loc = window.location.href.replace(
+        "//<%= @url_base %>/<%= component_settings.gh_pages_directory %>/latest",
+        "//<%= @url_base %>/<%= component_settings.gh_pages_directory %>/v" + <%= component_settings.gh_pages_version_var %>);
+      window.location.replace(loc);
+      location_updated = true;
+    }
+<% end %>    if (!location_updated) {
+      window.location.replace("<%= @default_url %>");
+    }
+  </script>
+</html>

data/toys/.data/templates/gh-pages-empty.html.erb

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+  </head>
+  <body>
+    <p>
+      No releases yet for <%= @component_settings.name %>.
+    </p>
+  </body>
+</html>

data/toys/.data/templates/gh-pages-gitignore.erb

@@ -0,0 +1 @@
+.DS_Store

data/toys/.data/templates/gh-pages-index.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=<%= @default_url %>">
+  </head>
+  <body>
+    <p>
+      <a href="<%= @default_url %>">Documentation for latest version</a>
+    </p>
+  </body>
+  <script>
+    window.location.replace("<%= @default_url %>");
+  </script>
+</html>

data/toys/.data/templates/release-hook-on-closed.yml.erb

@@ -0,0 +1,34 @@
+name: "[release hook] Process release"
+
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  contents: write # required for creating releases
+  pull-requests: write # required for updating label on PR, posting comments
+  issues: write # required for creating new issues on failed releases
+
+jobs:
+  release-process-request:
+    if: ${{ github.repository == '<%= @settings.repo_path %>' }}
+    env:
+      ruby_version: "3.4"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Ruby ${{ env.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.ruby_version }}
+      - name: Checkout repo
+        uses: actions/checkout@v5
+      - name: Install Toys
+        run: "gem install --no-document toys"
+      - name: Process release request
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          toys release _onclosed --verbose \
+            "--event-path=${{ github.event_path }}" \
+            < /dev/null

data/toys/.data/templates/release-hook-on-open.yml.erb

@@ -0,0 +1,30 @@
+name: "[release hook] Check commit messages"
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  release-check-commits:
+    if: ${{ github.repository == '<%= @settings.repo_path %>' }}
+    env:
+      ruby_version: "3.4"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Ruby ${{ env.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.ruby_version }}
+      - name: Checkout repo
+        uses: actions/checkout@v5
+        with:
+          ref: refs/pull/${{ github.event.pull_request.number }}/merge
+      - name: Install Toys
+        run: "gem install --no-document toys"
+      - name: Check commit messages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          toys release _onopen --verbose \
+            "--event-path=${{ github.event_path }}" \
+            < /dev/null

data/toys/.data/templates/release-hook-on-push.yml.erb

@@ -0,0 +1,32 @@
+name: "[release hook] Update open releases"
+
+on:
+  push:
+    branches:
+      - <%= @settings.main_branch %>
+
+permissions:
+  contents: write # required for pushing changes
+  pull-requests: write # required for updating open release PRs
+
+jobs:
+  release-update-open-requests:
+    if: ${{ github.repository == '<%= @settings.repo_path %>' }}
+    env:
+      ruby_version: "3.4"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Ruby ${{ env.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.ruby_version }}
+      - name: Checkout repo
+        uses: actions/checkout@v5
+      - name: Install Toys
+        run: "gem install --no-document toys"
+      - name: Update open releases
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          toys release _onpush --verbose \
+            < /dev/null

data/toys/.data/templates/release-perform.yml.erb

@@ -0,0 +1,46 @@
+name: Force release
+
+on:
+  workflow_dispatch:
+    inputs:
+      name:
+        description: Component to release
+        required: true
+      version:
+        description: Version to release
+        required: true
+      flags:
+        description: Extra flags to pass to the release script
+        required: false
+        default: ""
+
+permissions:
+  contents: write # required for creating releases
+  pull-requests: write # required for updating label on PR, posting comments
+  issues: write # required for creating new issues on failed releases
+
+jobs:
+  release-perform:
+    if: ${{ github.repository == '<%= @settings.repo_path %>' }}
+    env:
+      ruby_version: "3.4"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Ruby ${{ env.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.ruby_version }}
+      - name: Checkout repo
+        uses: actions/checkout@v5
+      - name: Install Toys
+        run: "gem install --no-document toys"
+      - name: Perform release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          toys release perform --yes --verbose \
+            "--release-ref=${{ github.sha }}" \
+            ${{ github.event.inputs.flags }} \
+            "${{ github.event.inputs.name }}" "${{ github.event.inputs.version }}" \
+            < /dev/null

data/toys/.data/templates/release-request.yml.erb

@@ -0,0 +1,37 @@
+name: Open release request
+
+on:
+  workflow_dispatch:
+    inputs:
+      names:
+        description: Components to release (leave blank to release all components)
+        required: false
+        default: ""
+
+permissions:
+  contents: write # required for pushing changes
+  pull-requests: write # required for creating release PRs
+
+jobs:
+  release-request:
+    if: ${{ github.repository == '<%= @settings.repo_path %>' }}
+    env:
+      ruby_version: "3.3"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Ruby ${{ env.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.ruby_version }}
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Install Toys
+        run: "gem install --no-document toys"
+      - name: Open release pull request
+        env:
+          GITHUB_TOKEN: ${{ secrets.TOYS_RELEASE_REQUEST_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          toys release request --yes --verbose \
+            "--target-branch=${{ github.ref }}" \
+            ${{ github.event.inputs.names }} \
+            < /dev/null

data/toys/.data/templates/release-retry.yml.erb

@@ -0,0 +1,42 @@
+name: Retry release
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_pr:
+        description: Release PR number
+        required: true
+      flags:
+        description: Extra flags to pass to the release script
+        required: false
+        default: ""
+
+permissions:
+  contents: write # required for creating releases
+  pull-requests: write # required for updating label on PR, posting comments
+  issues: write # required for creating new issues on failed releases
+
+jobs:
+  release-retry:
+    if: ${{ github.repository == '<%= @settings.repo_path %>' }}
+    env:
+      ruby_version: "3.4"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Ruby ${{ env.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.ruby_version }}
+      - name: Checkout repo
+        uses: actions/checkout@v5
+      - name: Install Toys
+        run: "gem install --no-document toys"
+      - name: Retry release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          toys release retry --yes --verbose \
+            ${{ github.event.inputs.flags }} \
+            "${{ github.event.inputs.release_pr }}" \
+            < /dev/null

data/toys/.lib/toys/release/artifact_dir.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Toys
+  module Release
+    ##
+    # Object that manages an artifact directory
+    #
+    class ArtifactDir
+      ##
+      # Create an ArtifactDir
+      #
+      # @param base_dir [String] Optional base directory, within which all the
+      #     artifact directories will be created. If not provided, a temporary
+      #     directory will be used.
+      #
+      def initialize(base_dir = nil)
+        @base_dir = base_dir
+        @needs_cleanup = false
+        @initialized = {}
+      end
+
+      ##
+      # Get the path to a directory with a given name. All calls to get with
+      # the same name will return the same directory path.
+      #
+      # @param name [String] Optional name. If not provided, a global default
+      #     name is used.
+      #
+      def get(name = nil)
+        dir_name = name ? "#{random_id}-#{name}" : random_id
+        path = ::File.join(base_dir, dir_name)
+        unless @initialized[path]
+          @initialized[path] = true
+          ::FileUtils.remove_entry(path, true)
+          ::FileUtils.mkdir_p(path)
+        end
+        path
+      end
+
+      ##
+      # Perform cleanup, removing the directories if they were created under a
+      # temporary directory.
+      #
+      def cleanup
+        if @needs_cleanup
+          ::FileUtils.remove_entry(@base_dir, true)
+          @needs_cleanup = false
+          @base_dir = nil
+        end
+      end
+
+      private
+
+      def base_dir
+        unless @base_dir
+          @base_dir = ::Dir.mktmpdir
+          @needs_cleanup = true
+        end
+        @base_dir
+      end
+
+      def random_id
+        @random_id ||= "#{rand(36**6).to_s(36)}#{::Time.now.to_i.to_s(36)}"
+      end
+    end
+  end
+end