decidim-maintainers_toolbox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98bbc7bc7f2fe89db2430fe013218ed8f73139241148f81e2b836001341a9edb
+  data.tar.gz: b2fcf684927d644818e40a3b47542bc9e71159ff8a220de40f45f7c02d479d90
+SHA512:
+  metadata.gz: e9fcb49b88f506a3d8522ed38afe5253bb6cbdff6f66287ce9e5d9b24800f37d10756784999b9ef3944c7a338ffb088d0216da9232d2b77f604a36dbb40cb7d9
+  data.tar.gz: 919e40cba79bb9d64c4cdaf6a7ec485423ffb64017f063ea696be0a5249e9d9eafd4bbf68c7cc85ee7aaf2059c3e083a637273e7f8b132953294f1fdc07c6c7b

data/README.md

@@ -0,0 +1,66 @@
+# Decidim::MaintainersToolbox
+
+Release related tools for the Decidim project.
+
+Tools for releasing, backporting, changelog generating, and working with GitHub
+
+## Installation
+
+This gem is meant to be used outside of bundler/Gemfile so we do not need to bump the version every time we release a new one to each of the releases branch.
+
+```console
+gem install decidim-maintainers_toolbox
+```
+
+## Usage
+
+This gem allows preparing and working with Decidim releases. Is it meant to be used by maintainers of the project. In the near future most of these tools will be used by `decidim-bot`.
+
+There are a couple differences with the rest of the gems of this repository:
+
+* About the versioning: as it has not decidim nor decidim-core as dependencies, and to keep it easy to work with, we will not have the same versioning as the others gems.
+* About the ruby version: to make it possible to work with older decidim versions, we will support the lowest supported ruby version.
+
+This is the reason why its in a different repository and not in the decidim repository.
+
+The main scripts are `decidim-backporter`, `decidim-backports-checker`, `decidim-changelog-generator` and `decidim-releaser`.
+
+### decidim-backporter
+
+See [Backports documentation](https://docs.decidim.org/en/develop/develop/backports)
+
+### decidim-backports-checker
+
+See [Backports documentation](https://docs.decidim.org/en/develop/develop/backports)
+
+### decidim-changelog-generator
+
+Used for generating the changelog with all the Pull Requests that goes to the current release. To be used automatically by the `releaser` script.
+
+### decidim-releaser
+
+See [Releasing new versions documentation](https://docs.decidim.org/en/develop/develop/maintainers/releases)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Releases
+
+As this gem is meant to be used outside of the main decidim gems, we will not follow the same versioning. We will release a new version of this gem every time we have a new feature or bugfix that we need to use. This also means that we will not follow the same release process.
+
+To release this gem, follow these steps:
+
+1. Bump the version number in `lib/decidim/maintainers_toolbox/version.rb` following [Semantic Versioning](https://semver.org/).
+1. Update the `CHANGELOG.md` with the new version and the changes.
+1. Commit the changes.
+1. Create a new tag with the version number.
+1. Push the changes and the tag to the repository.
+1. Run `rake build` to build the gem.
+1. Run `rake release` to publish the gem to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/decidim/decidim.

data/decidim-maintainers_toolbox.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/decidim/maintainers_toolbox/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "decidim-maintainers_toolbox"
+  spec.version = Decidim::MaintainersToolbox::VERSION
+  spec.authors = ["Andrés Pereira de Lucena"]
+  spec.email = ["andreslucena@gmail.com"]
+
+  spec.summary = "Release related tools for the Decidim project"
+  spec.description = "Tools for releasing, backporting, changelog generating, and working with GitHub"
+
+  spec.license = "AGPL-3.0"
+  spec.homepage = "https://decidim.org"
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/decidim/decidim/issues",
+    "documentation_uri" => "https://docs.decidim.org/",
+    "funding_uri" => "https://opencollective.com/decidim",
+    "homepage_uri" => "https://decidim.org",
+    "source_code_uri" => "https://github.com/decidim/decidim"
+  }
+  spec.required_ruby_version = ">= 2.7.5"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").select do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w(
+                        exe/
+                        lib/
+                        README.md
+                      ))
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 1.10"
+  spec.add_dependency "ruby-progressbar", "~> 1.7"
+  spec.add_dependency "thor", "~> 1.0"
+
+  spec.add_development_dependency "activesupport", "~> 6.1.7"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "webmock", "~> 3.18"
+end

data/exe/decidim-backporter

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "thor"
+
+require_relative "../lib/decidim/maintainers_toolbox/github_manager/querier"
+require_relative "../lib/decidim/maintainers_toolbox/github_manager/poster"
+require_relative "../lib/decidim/maintainers_toolbox/git_backport_manager"
+require_relative "../lib/decidim/maintainers_toolbox/backporter"
+
+class BackporterCLI < Thor
+  desc "", "Backport a pull request to another branch"
+  option :github_token, required: true, desc: <<~HELP
+    Required. Github Personal Access Token (PAT). It can be obtained from https://github.com/settings/tokens/new. You will need to create one with `public_repo` access.
+    Alternatively, you can use the `gh` CLI tool to authenticate with `gh auth token` (i.e. --github-token=$(gh auth token))
+  HELP
+  option :version_number, required: true, desc: "Required. The version number that you want to do the backport to. It must have the format MAJOR.MINOR."
+  option :pull_request_id, required: true, desc: "Required. The ID of the pull request that you want to make the backport from. It should have the \"type: fix\" label."
+  option :exit_with_unstaged_changes, type: :boolean, default: true, desc: <<~HELP
+    Optional. Whether the script should exit with an error if there are unstaged changes in the current project.
+  HELP
+  default_task :backport
+
+  def backport
+    Decidim::MaintainersToolbox::Backporter.new(
+      token: options[:github_token],
+      pull_request_id: options[:pull_request_id],
+      version_number: options[:version_number],
+      exit_with_unstaged_changes: options[:exit_with_unstaged_changes]
+    ).call
+  rescue Decidim::MaintainersToolbox::GithubManager::Querier::Base::InvalidMetadataError
+    puts "Metadata was not returned from the server. Please check that the provided pull request ID and GitHub token are correct."
+  end
+
+  def help
+    super("backport")
+  end
+
+  def self.exit_on_failure?
+    true
+  end
+end
+
+BackporterCLI.start(ARGV)

data/exe/decidim-backports-checker

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "thor"
+
+require_relative "../lib/decidim/maintainers_toolbox/git_backport_checker"
+
+class BackportsCheckerCLI < Thor
+  desc "", <<~HELP
+    Backports checker. Shows the status of the pull requests opened in the last days
+
+    The output by default is for the terminal. It uses a color code to differentiate the status of the Pull Requests, following the colors of GitHub:
+    - \e[34mPurple\e[0m: closed with a merge
+    - \e[35mRed\e[0m: closed without being merge
+    - \e[32mGreen\e[0m: opened without being merge
+  HELP
+  option :github_token, required: true, desc: <<~HELP
+    Required. Github Personal Access Token (PAT). It can be obtained from https://github.com/settings/tokens/new. You will need to create one with `public_repo` access.
+    Alternatively, you can use the `gh` CLI tool to authenticate with `gh auth token` (i.e. --github-token=$(gh auth token))
+  HELP
+  option :last_version_number, required: true, desc: <<~HELP
+    Required. The version number of the last supported version that you want to do the backports to. It must have the format MAJOR.MINOR.
+  HELP
+  option :days_to_check_from, required: false, default: 90, type: :numeric, desc: "How many days since the pull requests were merged we will check from."
+  default_task :backports_checker
+
+  def backports_checker
+    checker = Decidim::MaintainersToolbox::GitBackportChecker.new(
+      token: options[:github_token],
+      last_version_number: options[:last_version_number],
+      days_to_check_from: options[:days_to_check_from]
+    )
+    checker.call
+    puts checker.cli_report
+  rescue Decidim::MaintainersToolbox::GithubManager::Querier::Base::InvalidMetadataError
+    puts "Metadata was not returned from the server. Please check that the provided GitHub token is correct."
+  end
+
+  def help
+    super("backports_checker")
+  end
+
+  def self.exit_on_failure?
+    true
+  end
+end
+
+BackportsCheckerCLI.start(ARGV)

data/exe/decidim-changelog-generator

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "thor"
+
+require_relative "../lib/decidim/maintainers_toolbox/changelog_generator"
+
+class ChangeLogGeneratorCLI < Thor
+  desc "", <<~HELP
+    Decidim's changelog generator. It will generate a changelog based on the pull requests merged since a given SHA
+    This script will generate the sections needed for the changelog, using the
+    labels of the merged PRs as a source of truth. It will add a section at the
+    end, "Unsorted", with the list of PRs that could not be classified.
+    It ignores any Crowdin PR.
+  HELP
+
+  option :github_token, required: true, desc: <<~HELP
+    Required. Github Personal Access Token (PAT). It can be obtained from https://github.com/settings/tokens/new. You will need to create one with `public_repo` access.
+    Alternatively, you can use the `gh` CLI tool to authenticate with `gh auth token` (i.e. --github-token=$(gh auth token))
+  HELP
+  option :since_sha, required: true, desc: <<~HELP
+    Required. The git commit SHA from which to consider the changes. It is
+    usually the last commit that modified the `.decidim_version` file.
+  HELP
+
+  default_task :changelog_generator
+
+  def changelog_generator
+    Decidim::MaintainersToolbox::ChangeLogGenerator.new(
+      token: options[:github_token],
+      since_sha: options[:since_sha]
+    ).call
+  rescue Decidim::MaintainersToolbox::ChangeLogGenerator::InvalidMetadataError
+    puts "Metadata was not returned from the server. Please check that the provided GitHub token is correct."
+  end
+
+  def help
+    super("changelog_generator")
+  end
+
+  def self.exit_on_failure?
+    true
+  end
+end
+
+ChangeLogGeneratorCLI.start(ARGV)

data/exe/decidim-releaser

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "thor"
+
+require_relative "../lib/decidim/maintainers_toolbox/releaser"
+
+class ReleaserCLI < Thor
+  desc "", "Make the branch for preparing a release"
+  option :github_token, required: true, desc: <<~HELP
+    Required. Github Personal Access Token (PAT). It can be obtained from https://github.com/settings/tokens/new. You will need to create one with `public_repo` access.
+    Alternatively, you can use the `gh` CLI tool to authenticate with `gh auth token` (i.e. --github-token=$(gh auth token))
+  HELP
+  option :version_type, enum: %w(rc minor patch), required: true, desc: <<~HELP
+    Required. The kind of release that you want to prepare.
+  HELP
+  option :exit_with_unstaged_changes, type: :boolean, default: true, desc: <<~HELP
+    Optional. Whether the script should exit with an error if there are unstaged changes in the current project.
+  HELP
+  default_task :releaser
+
+  def releaser
+    Decidim::MaintainersToolbox::Releaser.new(
+      token: options[:github_token],
+      version_type: options[:version_type],
+      exit_with_unstaged_changes: options[:exit_with_unstaged_changes]
+    ).call
+  rescue Decidim::MaintainersToolbox::Releaser::InvalidMetadataError
+    puts "Metadata was not returned from the server. Please check that the GitHub token is correct."
+  end
+
+  def help
+    super("releaser")
+  end
+
+  def self.exit_on_failure?
+    true
+  end
+end
+
+ReleaserCLI.start(ARGV)

data/lib/decidim/maintainers_toolbox/backporter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Decidim
+  module MaintainersToolbox
+    class Backporter
+      class InvalidMetadataError < StandardError; end
+
+      # @param token [String] token for GitHub authentication
+      # @param pull_request_id [String] the ID of the pull request that we want to backport
+      # @param version_number [String] the version number of the release that we want to make the backport to
+      # @param exit_with_unstaged_changes [Boolean] wheter we should exit cowardly if there is any unstaged change
+      def initialize(token:, pull_request_id:, version_number:, exit_with_unstaged_changes:)
+        @token = token
+        @pull_request_id = pull_request_id
+        @version_number = version_number
+        @exit_with_unstaged_changes = exit_with_unstaged_changes
+      end
+
+      # Handles the different tasks to create a backport:
+      # * Gets the metadata of a pull request on GitHub
+      # * Appls thi commit to another brach and push it to the remote repository
+      # * Creates the pull request on GitHub
+      #
+      # @raise [InvalidMetadataError] if we could not get the information of this pull quest
+      # @return [void]
+      def call
+        metadata = pull_request_metadata
+        make_cherrypick_and_branch(metadata)
+        create_pull_request(metadata)
+        Decidim::MaintainersToolbox::GitBackportManager.checkout_develop
+      end
+
+      private
+
+      attr_reader :token, :pull_request_id, :version_number, :exit_with_unstaged_changes
+
+      # Asks the metadata for a given issue or pull request on GitHub API
+      #
+      # @return [Faraday::Response] An instance that represents an HTTP response from making an HTTP request
+      def pull_request_metadata
+        Decidim::MaintainersToolbox::GithubManager::Querier::ByIssueId.new(
+          token: token,
+          issue_id: pull_request_id
+        ).call
+      end
+
+      # Handles all the different tasks involved on a backport with the git command line utility
+      #
+      # @return [void]
+      def make_cherrypick_and_branch(metadata)
+        Decidim::MaintainersToolbox::GitBackportManager.new(
+          pull_request_id: pull_request_id,
+          release_branch: release_branch,
+          backport_branch: backport_branch(metadata[:title]),
+          exit_with_unstaged_changes: exit_with_unstaged_changes
+        ).call
+      end
+
+      # Creates the pull request with GitHub API
+      #
+      # @return [Faraday::Response] An instance that represents an HTTP response from making an HTTP request
+      def create_pull_request(metadata)
+        params = {
+          title: "Backport '#{metadata[:title]}' to v#{version_number}",
+          body: "#### :tophat: What? Why?\n\nBackport ##{pull_request_id} to v#{version_number}\n\n:hearts: Thank you!",
+          labels: (metadata[:labels] << "backport"),
+          head: backport_branch(metadata[:title]),
+          base: release_branch
+        }
+
+        Decidim::MaintainersToolbox::GithubManager::Poster.new(
+          token: token,
+          params: params
+        ).call
+      end
+
+      # Name of the release branch
+      #
+      # @return [String] name of the release branch
+      def release_branch
+        "release/#{version_number}-stable"
+      end
+
+      # Name of the backport branch
+      #
+      # @return [String] name of the backport branch
+      def backport_branch(pull_request_title)
+        "backport/#{version_number}/#{slugify(pull_request_title).slice!(0, 30)}-#{pull_request_id}"
+      end
+
+      # Converts a string with spaces to a slug
+      # It changes it to lowercase and removes spaces
+      #
+      # @return [String] slugged string
+      def slugify(string)
+        string.downcase.strip.gsub(" ", "-").gsub(/[^\w-]/, "")
+      end
+    end
+  end
+end

data/lib/decidim/maintainers_toolbox/backports_reporter/cli_report.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/filters"
+require_relative "report"
+
+module Decidim
+  module MaintainersToolbox
+    module BackportsReporter
+      class CLIReport < Decidim::MaintainersToolbox::BackportsReporter::Report
+        private
+
+        def output_head
+          head = "| #{"ID".center(6)} | #{"Title".center(83)} | Backport v#{last_version_number} | Backport v#{penultimate_version_number} |\n"
+          head += "|#{"-" * 8}|#{"-" * 85}|#{"-" * 16}|#{"-" * 16}|\n"
+          head
+        end
+
+        def output_line(line)
+          output = "| ##{line[:id].to_s.center(5)} "
+          output += "| #{line[:title].truncate(83).ljust(84, " ")}"
+          output += "| #{format_backport(line[:related_issues], "v#{last_version_number}")}"
+          output += "| #{format_backport(line[:related_issues], "v#{penultimate_version_number}")}|\n"
+          output
+        end
+
+        def format_backport(related_issues, version)
+          none = "None".center(15, " ")
+          return none if related_issues.empty?
+
+          pull_request = extract_backport_pull_request_for_version(related_issues, version)
+          return none if pull_request.nil?
+
+          "\e[#{state_color(pull_request[:state])}m##{pull_request[:id]}\e[0m".center(24, " ")
+        end
+
+        def state_color(state)
+          {
+            closed: "35",
+            merged: "34",
+            open: "32"
+          }[state.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/decidim/maintainers_toolbox/backports_reporter/csv_report.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "report"
+
+module Decidim
+  module MaintainersToolbox
+    module BackportsReporter
+      class CSVReport < Decidim::MaintainersToolbox::BackportsReporter::Report
+        private
+
+        def output_head
+          "ID;Title;Backport v#{last_version_number};Backport v#{penultimate_version_number}\n"
+        end
+
+        def output_line(line)
+          output = "#{line[:id]};"
+          output += "#{line[:title]};"
+          output += "#{format_backport(line[:related_issues], "v#{last_version_number}")};"
+          output += "#{format_backport(line[:related_issues], "v#{penultimate_version_number}")}\n"
+          output
+        end
+
+        def format_backport(related_issues, version)
+          return if related_issues.empty?
+
+          pull_request = extract_backport_pull_request_for_version(related_issues, version)
+          return if pull_request.nil?
+
+          "#{pull_request[:state]}|#{pull_request[:id]}"
+        end
+      end
+    end
+  end
+end

data/lib/decidim/maintainers_toolbox/backports_reporter/report.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Decidim
+  module MaintainersToolbox
+    module BackportsReporter
+      # Abstract class for the different formats
+      class Report
+        attr_reader :report, :last_version_number
+
+        def initialize(report:, last_version_number:)
+          @report = report
+          @last_version_number = last_version_number
+        end
+
+        def call
+          output_report
+        end
+
+        private
+
+        def penultimate_version_number
+          major, minor = last_version_number.split(".")
+
+          "#{major}.#{minor.to_i - 1}"
+        end
+
+        def output_report
+          output = output_head
+          report.each do |line|
+            next if backports_merged?(line[:related_issues])
+
+            output += output_line(line)
+          end
+          output
+        end
+
+        def output_head
+          raise "Called abstract method: output_head"
+        end
+
+        def output_line(_line)
+          raise "Called abstract method: output_line"
+        end
+
+        def extract_backport_pull_request_for_version(related_issues, version)
+          related_issues = related_issues.select do |pull_request|
+            pull_request[:title].start_with?("Backport") && pull_request[:title].include?(version)
+          end
+          return if related_issues.empty?
+
+          related_issues.first
+        end
+
+        def backports_merged?(related_issues)
+          return if related_issues.empty?
+
+          latest_pr = extract_backport_pull_request_for_version(related_issues, "v#{last_version_number}")
+          penultimate_pr = extract_backport_pull_request_for_version(related_issues, "v#{penultimate_version_number}")
+
+          return unless [latest_pr, penultimate_pr].all?
+
+          latest_pr[:state] == "merged" && penultimate_pr[:state] == "merged"
+        end
+      end
+    end
+  end
+end