toys-release 0.1.0

data/toys/gen-workflows.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+desc "Generate GitHub Actions workflow files"
+
+long_desc \
+  "This tool generates workflow files for GitHub Actions."
+
+flag :yes, "--yes", "-y" do
+  desc "Automatically answer yes to all confirmations"
+end
+
+include :exec
+include :terminal, styled: true
+
+# Context for ERB templates
+class ErbContext
+  def initialize(settings)
+    @settings = settings
+  end
+
+  def self.get(settings)
+    new(settings).instance_eval { binding }
+  end
+end
+
+def run
+  require "erb"
+  require "toys/release/environment_utils"
+  require "toys/release/repo_settings"
+
+  @utils = Toys::Release::EnvironmentUtils.new(self)
+  @settings = Toys::Release::RepoSettings.load_from_environment(@utils)
+
+  unless @settings.enable_release_automation?
+    puts "Release automation disabled in settings."
+    unless yes || confirm("Create workflow files anyway? ", default: false)
+      @utils.error("Aborted.")
+    end
+  end
+
+  @workflows_dir = ::File.join(context_directory, ".github", "workflows")
+  files = [
+    "release-hook-on-closed.yml",
+    "release-hook-on-push.yml",
+    "release-perform.yml",
+    "release-request.yml",
+    "release-retry.yml",
+  ]
+
+  files.each { |name| generate(name) }
+end
+
+def generate(name)
+  destination = ::File.join(@workflows_dir, name)
+  if ::File.readable?(destination)
+    puts "Destination file #{destination} exists.", :yellow, :bold
+    return unless yes || confirm("Overwrite? ", default: true)
+  else
+    return unless yes || confirm("Create file #{destination}? ", default: true)
+  end
+
+  template_path = find_data("templates/#{name}.erb")
+  raise "Unable to find template #{name}.erb" unless template_path
+  erb = ::ERB.new(::File.read(template_path))
+
+  ::File.open(destination, "w") do |file|
+    file.write(erb.result(ErbContext.get(@settings)))
+    puts "Wrote #{destination}.", :green, :bold
+  end
+end

data/toys/perform.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+desc "Perform a release"
+
+long_desc \
+  "This tool performs an official release. It is normally called from a" \
+    " GitHub Actions workflow, but can also be executed locally if the" \
+    " proper credentials are present.",
+  "",
+  "Normally, releases should be initiated using the 'request' tool, invoked" \
+    " either locally or from GitHub Actions. That tool will automatically" \
+    " update the library version and changelog based on the commits since" \
+    " the last release, and will open a pull request that you can merge to" \
+    " actually perform the release. The 'perform' tool should be used only" \
+    " if the version and changelog commits are already committed.",
+  "",
+  "When invoked, this tool first performs pre-checks including:",
+  "* The git workspace must be clean (no new, modified, or deleted files)",
+  "* The remote repo must be the correct repo configured in releases.yml",
+  "* All GitHub checks for the release to commit must have succeeded",
+  "",
+  "The tool then performs the necessary release tasks for each component." \
+    " It also ensures each version file and changelog are properly formatted" \
+    " and match the release version if given."
+
+remaining_args :components do
+  accept(/^[\w-]+(?:[=:][\w.-]+)?$/)
+  desc "Components to release"
+  long_desc \
+    "Each remaining argument should consist of a component name, and optional" \
+      " version number separated by a equal sign, i.e.",
+    ["    <name>[=<version>]"],
+    "",
+    "The version to release is determined by the version file and changelog." \
+      " The version given on the command line, if provided, is used only for" \
+      " verification."
+end
+
+flag_group desc: "Flags" do
+  flag :dry_run, "--[no-]dry-run" do
+    desc "Run in dry-run mode."
+    long_desc \
+      "Run in dry-run mode, where checks are made and releases are built" \
+      " but are not pushed."
+  end
+  flag :git_remote, "--git-remote=VAL" do
+    default "origin"
+    desc "The name of the git remote"
+    long_desc \
+      "The name of the git remote pointing at the canonical repository." \
+      " Defaults to 'origin'."
+  end
+  flag :release_ref, "--release-ref=VAL", "--release-sha=VAL" do
+    desc "The commit to use for the release"
+    long_desc \
+      "Specifies a ref (branch or SHA) for the release. Optional. Defaults" \
+      " to the current HEAD."
+  end
+  flag :enable_prechecks, "--[no-]enable-prechecks" do
+    default true
+    desc "Enables pre-release checks. Enabled by default."
+  end
+  flag :release_pr, "--release-pr=VAL" do
+    accept ::Integer
+    desc "Release pull request number"
+    long_desc \
+      "Update the given release pull request number. Optional."
+  end
+  flag :work_dir, "--work-dir=PATH" do
+    desc "Set the directory for artifacts and temporary files"
+    long_desc \
+      "If provided, the given directory path is used for artifacts and" \
+        " temporary files, and is left intact after the release so the" \
+        " artifacts can be inspected. If omitted, a new temporary directory" \
+        " is created, and is automatically deleted after the release."
+  end
+  flag :yes, "--yes", "-y" do
+    desc "Automatically answer yes to all confirmations"
+  end
+  flag :rubygems_api_key, "--rubygems-api-key=VAL" do
+    desc "Set the Rubygems API key"
+    long_desc \
+      "Use the given Rubygems API key when pushing to Rubygems. Deprecated;" \
+      " prefer just setting the `GEM_HOST_API_KEY` environment variable."
+  end
+  flag :gh_token, "--gh-token=VAL" do
+    desc "Set the GitHub token"
+    long_desc \
+      "Use the given GitHub token when pushing to GitHub. Deprecated; prefer" \
+      " just setting the `GITHUB_TOKEN` environment variable."
+  end
+  flag :enable_releases, "--enable-releases=VAL" do
+    desc "Deprecated and unused"
+  end
+end
+
+include :exec
+include :terminal, styled: true
+
+def run
+  ::Dir.chdir(context_directory)
+  require "toys/release/environment_utils"
+  require "toys/release/repository"
+  require "toys/release/repo_settings"
+  require "toys/release/performer"
+
+  setup_arguments
+  setup_performer
+  components.each do |component_spec|
+    name, version = component_spec.split(/[:=]/, 2)
+    confirmation_ui(name, version)
+    gem_version = version ? ::Gem::Version.new(version) : nil
+    @performer.perform_adhoc_release(name, assert_version: gem_version)
+  end
+  puts @performer.build_report_text
+end
+
+def setup_arguments
+  [
+    :git_remote,
+    :release_ref,
+    :release_pr,
+    :rubygems_api_key,
+    :gh_token,
+    :work_dir,
+  ].each do |key|
+    set(key, nil) if get(key).to_s.empty?
+  end
+  set(:dry_run, /^t/i.match?(::ENV["TOYS_RELEASE_DRY_RUN"].to_s)) if dry_run.nil?
+  ::ENV["GEM_HOST_API_KEY"] = rubygems_api_key if rubygems_api_key
+  ::ENV["GITHUB_TOKEN"] = gh_token if gh_token
+end
+
+def setup_performer
+  @utils = Toys::Release::EnvironmentUtils.new(self)
+  @repo_settings = Toys::Release::RepoSettings.load_from_environment(@utils)
+  @repository = Toys::Release::Repository.new(@utils, @repo_settings)
+  @repository.git_set_user_info
+  @performer = Toys::Release::Performer.new(@repository,
+                                            release_ref: release_ref,
+                                            release_pr: release_pr,
+                                            enable_prechecks: enable_prechecks,
+                                            git_remote: git_remote,
+                                            work_dir: work_dir,
+                                            dry_run: dry_run)
+end
+
+def confirmation_ui(name, version)
+  return if yes
+  return if confirm("Release #{name} #{version}? ", :bold, default: false)
+  @utils.error("Release aborted")
+end

data/toys/request.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+desc "Open a release request"
+
+long_desc \
+  "This tool opens release pull requests for the specified releasable" \
+  " components. It analyzes the commits since the last release, and updates" \
+    " each component's version and changelog accordingly. This tool is" \
+    " normally called from a GitHub Actions workflow, but can also be" \
+    " executed locally.",
+  "",
+  "When invoked, this tool first performs checks including:",
+  "* The git workspace must be clean (no new, modified, or deleted files)",
+  "* The remote repo must be the correct repo configured in releases.yml",
+  "* All GitHub checks for the release commit must have succeeded",
+  "",
+  "The tool then creates release pull requests for each component:",
+  "* It collects all commit messages since the previous release.",
+  "* It builds a changelog using properly formatted conventional commit" \
+    " messages of type 'fix', 'feat', and 'docs', and any that indicate a" \
+    " breaking change.",
+  "* Unless a specific version is provided via flags, it infers a new version" \
+    " number using the implied semver significance of the commit messages.",
+  "* It edits the changelog and version Ruby files and pushes a commit to a" \
+    " release branch.",
+  "* It opens a release pull request.",
+  "",
+  "Release pull requests may be edited to modify the version and/or changelog" \
+    " before merging. In repositories that have release automation enabled," \
+    " the release script will run automatically when a release pull request" \
+    " is merged."
+
+remaining_args :components do
+  accept(/^[\w-]+(?:[=:][\w.-]+)?$/)
+  desc "Components to release"
+  long_desc \
+    "Each remaining argument should consist of a component name, and optional" \
+      " version spec separated by a equal sign, i.e.",
+    ["    <name>[=<version>]"],
+    "",
+    "The version can be a literal version number, or one of the semver" \
+      " change types 'major', 'minor', or 'patch'. It can also be omitted." \
+      " If the version is omitted, a semver change type will be inferred" \
+      " from the conventional commit message history, and the component will" \
+      " be released only if at least one significant releasable commit tag" \
+      " (such as 'feat:', 'fix:', or 'docs:') is found.",
+    "",
+    "Note that any coordination groups are honored. If you release at least" \
+      " one component within a group, all components in the group will be" \
+      " forced to release with the same version.",
+    "",
+    "The special name 'all' can be used to specify all components. You can" \
+      " also provide a version to force all components to be released with" \
+      " that version, e.g. 'all=1.2.3'.",
+    "",
+    "If no components are provided, all components with releasable changes" \
+      " are released. That is, not providing any components is equivalent to" \
+      " specifying 'all' without a version."
+end
+
+flag :git_remote, "--git-remote=VAL" do
+  default "origin"
+  desc "The name of the git remote"
+  long_desc \
+    "The name of the git remote pointing at the canonical repository." \
+    " Defaults to 'origin'."
+end
+flag :target_branch, "--release-ref=VAL", "--target-branch=VAL" do
+  desc "Target branch for the release"
+  long_desc "The target branch for the release request. Defaults to HEAD."
+end
+flag :yes, "--yes", "-y" do
+  desc "Automatically answer yes to all confirmations"
+end
+
+include :exec
+include :terminal, styled: true
+
+def run
+  setup
+  @utils = Toys::Release::EnvironmentUtils.new(self)
+  @repo_settings = Toys::Release::RepoSettings.load_from_environment(@utils)
+  @repository = prepare_repository
+  @request_spec = build_request_spec
+  @request_logic = Toys::Release::RequestLogic.new(@repository, @request_spec)
+  @request_logic.verify_component_status
+  @request_logic.verify_pull_request_status
+  confirmation_ui
+  @pull_request = create_pull_request
+  result_ui(@pull_request.number)
+end
+
+def setup
+  ::Dir.chdir(context_directory)
+  require "toys/release/environment_utils"
+  require "toys/release/repository"
+  require "toys/release/repo_settings"
+  require "toys/release/request_logic"
+  require "toys/release/request_spec"
+end
+
+def prepare_repository
+  repository = Toys::Release::Repository.new(@utils, @repo_settings)
+  repository.git_set_user_info
+  repository.verify_git_clean
+  repository.verify_repo_identity(remote: git_remote)
+  set(:target_branch, nil) if get(:target_branch).to_s.empty?
+  set(:target_branch, repository.git_prepare_branch(git_remote, branch: target_branch))
+  repository.verify_github_checks(ref: target_branch)
+  repository
+end
+
+def build_request_spec
+  request_spec = Toys::Release::RequestSpec.new(@utils)
+  set(:components, ["all"]) if components.empty?
+  components.each do |component_spec|
+    component_spec = component_spec.split(/[:=]/)
+    name = component_spec[0]
+    version = component_spec[1]
+    if name == "all"
+      @repository.all_components.each do |component|
+        request_spec.add(component.name, version: version)
+      end
+    else
+      request_spec.add(name, version: version)
+    end
+  end
+  request_spec.resolve_versions(@repository, release_ref: target_branch)
+  request_spec
+end
+
+def confirmation_ui
+  puts("Opening a request to release the following:", :bold)
+  @request_spec.resolved_components.each do |component|
+    puts("* #{component.component_name} version #{component.last_version} -> #{component.version}")
+  end
+  unless yes || confirm("Create release PR? ", :bold, default: true)
+    @utils.error("Release aborted")
+  end
+end
+
+def create_pull_request
+  release_branch = @request_logic.determine_release_branch
+  commit_title = @request_logic.build_commit_title
+  commit_details = @request_logic.build_commit_details
+  signoff = @repository.settings.signoff_commits?
+  @repository.create_branch(release_branch)
+  @request_logic.change_files
+  @repository.git_commit(commit_title, commit_details: commit_details, signoff: signoff)
+  body = @request_logic.build_pr_body
+  labels = @request_logic.determine_pr_labels
+  @repository.create_pull_request(base_branch: target_branch,
+                                  remote: git_remote,
+                                  title: commit_title,
+                                  body: body,
+                                  labels: labels)
+end
+
+def result_ui(pr_number)
+  repo = @repository.settings.repo_path
+  puts("Created pull request: https://github.com/#{repo}/pull/#{pr_number}", :bold)
+end

data/toys/retry.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+desc "Releases pending releasable components for a pull request"
+
+long_desc \
+  "This tool continues the releases associated with a release pull request." \
+    " It is normally used to retry or continue releases that aborted due to" \
+    " an error. This tool is normally called from a GitHub Actions workflow," \
+    " but can also be executed locally if the proper credentials are present."
+
+required_arg :release_pr, accept: Integer do
+  desc "Release pull request number. Required."
+end
+flag_group desc: "Flags" do
+  flag :dry_run, "--[no-]dry-run" do
+    desc "Run in dry-run mode."
+    long_desc \
+      "Run in dry-run mode, where checks are made and releases are built" \
+      " but are not pushed."
+  end
+  flag :gh_pages_dir, "--gh-pages-dir=VAL" do
+    desc "The directory to use for the gh-pages branch"
+    long_desc \
+      "Set to the path of a directory to use as the gh-pages workspace when" \
+      " building and pushing gem documentation. If left unset, a temporary" \
+      " directory will be created (and removed when finished)."
+  end
+  flag :git_remote, "--git-remote=VAL" do
+    default "origin"
+    desc "The name of the git remote"
+    long_desc \
+      "The name of the git remote pointing at the canonical repository." \
+      " Defaults to 'origin'."
+  end
+  flag :release_ref, "--release-ref=VAL", "--release-sha=VAL" do
+    desc "Override the commit for the release"
+    long_desc \
+      "The SHA or ref to release from. This can be used if additional" \
+      " changes are needed to fix the release. If not given, the merge SHA" \
+      " of the pull request is used."
+  end
+  flag :enable_prechecks, "--[no-]enable-prechecks" do
+    default true
+    desc "Enables pre-release checks. Enabled by default."
+    long_desc \
+      "Enables pre-release checks. Enabled by default. It may occasionally" \
+      " be useful to disable this to repair a broken release, but it is" \
+      " generally not recommended."
+  end
+  flag :yes, "--yes", "-y" do
+    desc "Automatically answer yes to all confirmations"
+  end
+  flag :rubygems_api_key, "--rubygems-api-key=VAL" do
+    desc "Set the Rubygems API key"
+    long_desc \
+      "Use the given Rubygems API key when pushing to Rubygems. Deprecated;" \
+      " prefer just setting the `GEM_HOST_API_KEY` environment variable."
+  end
+  flag :enable_releases, "--enable-releases=VAL" do
+    desc "Deprecated and unused"
+  end
+end
+
+include :exec
+include :terminal, styled: true
+
+def run
+  ::Dir.chdir(context_directory)
+  setup_objects
+  verify_release_pr
+  setup_params
+  @repository.at_sha(release_ref) do
+    perform_pending_releases
+  end
+end
+
+def setup_objects
+  require "toys/release/environment_utils"
+  require "toys/release/repository"
+  require "toys/release/repo_settings"
+  require "toys/release/performer"
+
+  @utils = Toys::Release::EnvironmentUtils.new(self)
+  @repo_settings = Toys::Release::RepoSettings.load_from_environment(@utils)
+  @repository = Toys::Release::Repository.new(@utils, @repo_settings)
+  @repository.git_set_user_info
+end
+
+def verify_release_pr
+  @pr_info = @repository.load_pr(release_pr)
+  @utils.error("Could not load pull request ##{release_pr}") unless @pr_info
+  expected_labels = [@repo_settings.release_pending_label, @repo_settings.release_error_label]
+  return if @pr_info["labels"].any? { |label| expected_labels.include?(label["name"]) }
+  warning = "PR #{release_pr} doesn't have the release pending or release error label."
+  if yes
+    logger.warn(warning)
+    return
+  end
+  unless confirm("#{warning} Proceed anyway? ", :bold, default: false)
+    @utils.error("Release aborted.")
+  end
+end
+
+def setup_params
+  [:gh_pages_dir, :rubygems_api_key].each do |key|
+    set(key, nil) if get(key).to_s.empty?
+  end
+  ::ENV["GEM_HOST_API_KEY"] = rubygems_api_key if rubygems_api_key
+  set(:dry_run, /^t/i.match?(::ENV["TOYS_RELEASE_DRY_RUN"].to_s)) if dry_run.nil?
+  set :release_ref, @repository.current_sha(release_ref || @pr_info["merge_commit_sha"])
+end
+
+def create_performer
+  Toys::Release::Performer.new(@repository,
+                               release_ref: release_ref,
+                               release_pr: release_pr,
+                               enable_prechecks: enable_prechecks,
+                               git_remote: git_remote,
+                               gh_pages_dir: gh_pages_dir,
+                               dry_run: dry_run)
+end
+
+def perform_pending_releases
+  @repository.wait_github_checks(release_ref) if enable_prechecks
+  performer = create_performer
+  performer.perform_pr_releases
+  performer.report_results
+  if performer.error?
+    @utils.error("Releases reported failure")
+  else
+    puts("All releases completed successfully", :bold, :green)
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: toys-release
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel Azuma
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: toys-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+description: Toys-Release is a Ruby library release system using GitHub Actions and
+  Toys. It interprets conventional commit 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.
+email:
+- dazuma@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- docs/guide.md
+- lib/toys-release.rb
+- lib/toys/release/version.rb
+- toys/.data/templates/gh-pages-404.html.erb
+- toys/.data/templates/gh-pages-empty.html.erb
+- toys/.data/templates/gh-pages-gitignore.erb
+- toys/.data/templates/gh-pages-index.html.erb
+- toys/.data/templates/release-hook-on-closed.yml.erb
+- toys/.data/templates/release-hook-on-open.yml.erb
+- toys/.data/templates/release-hook-on-push.yml.erb
+- toys/.data/templates/release-perform.yml.erb
+- toys/.data/templates/release-request.yml.erb
+- toys/.data/templates/release-retry.yml.erb
+- toys/.lib/toys/release/artifact_dir.rb
+- toys/.lib/toys/release/change_set.rb
+- toys/.lib/toys/release/changelog_file.rb
+- toys/.lib/toys/release/component.rb
+- toys/.lib/toys/release/environment_utils.rb
+- toys/.lib/toys/release/performer.rb
+- toys/.lib/toys/release/pull_request.rb
+- toys/.lib/toys/release/repo_settings.rb
+- toys/.lib/toys/release/repository.rb
+- toys/.lib/toys/release/request_logic.rb
+- toys/.lib/toys/release/request_spec.rb
+- toys/.lib/toys/release/semver.rb
+- toys/.lib/toys/release/steps.rb
+- toys/.lib/toys/release/version_rb_file.rb
+- toys/.toys.rb
+- toys/_onclosed.rb
+- toys/_onopen.rb
+- toys/_onpush.rb
+- toys/create-labels.rb
+- toys/gen-gh-pages.rb
+- toys/gen-settings.rb
+- toys/gen-workflows.rb
+- toys/perform.rb
+- toys/request.rb
+- toys/retry.rb
+homepage: https://github.com/dazuma/toys
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-release/v0.1.0/file.CHANGELOG.html
+  source_code_uri: https://github.com/dazuma/toys/tree/main/toys-release
+  bug_tracker_uri: https://github.com/dazuma/toys/issues
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-release/v0.1.0
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Release system using GitHub Actions and Toys
+test_files: []