create_github_release 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6346efaa6cdc82095a7e3220d74dd359a10843f24f81c50037d9c85dbdc9dd8
-  data.tar.gz: 674903481a785730fde4910bd0994f0cbcbed3196e3355e37775058bc1b0215d
+  metadata.gz: b7feefb0f3ef554c8aea3c693cdbbed30aab587be5dc44631101898caadfa658
+  data.tar.gz: d342cd8c38e03ca012d5b70daf832642a7434c647d4466d9cd0969e9f4278926
 SHA512:
-  metadata.gz: bad25c4943faf700f6cb8593e42a5d2b2f879ec9e6f65fdcab120568e0fc4563b8e4972e76a595c8e2bfaabacba8ee5da98a9ab919bbc763a4aafdc889ba8588
-  data.tar.gz: 61b4028671f28e714cb88cfade742d515f45d7dba45a158865e2d94ea1ec3e609038ae95446274d018839f162a0743f5ae34f954ae1550016ad99b7afa6d07cf
+  metadata.gz: 122c8e2198ceb28fa9e429f851e7c6d821cadc71fb5a3ade6749c520d1ae7d427159f7059e1455a3a2b15294d8e1125e75451d4d1996fceef63f07e7b88b4ffb
+  data.tar.gz: e6d1a7abe65328fc51161458934709b9ae3e747573398f4ef71bcdfad4023f865b76ebd6836fe7622183a90909da9498ca6ec30b29deac89d9608b0a225e8d7d

data/.markdownlint.yml

@@ -1,7 +1,7 @@
 default: true
 
 # Unordered list indentation
-MD007: { indent: 4 }
+MD007: { indent: 2 }
 
 # Line length
 MD013: { line_length: 90, tables: false, code_blocks: false }

data/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v1.0.0 (2023-02-05)
+
+[Full Changelog](https://github.com/main-branch/create_github_release/compare/v0.3.0..v1.0.0)
+
+Changes since v0.3.0:
+
+* bfd40e6 Handle the first release of a gem (#32)
+* 7a76148 Release v0.3.0 (#31)
+
 ## v0.3.0 (2023-01-29)
 
 [Full Changelog](https://github.com/main-branch/create_github_release/compare/v0.2.1..v0.3.0)

data/README.md

@@ -5,29 +5,47 @@
  [![Maintainability](https://api.codeclimate.com/v1/badges/b8c0af10b15a0ffeb1a1/maintainability)](https://codeclimate.com/github/main-branch/create_github_release/maintainability)
  [![Test Coverage](https://api.codeclimate.com/v1/badges/b8c0af10b15a0ffeb1a1/test_coverage)](https://codeclimate.com/github/main-branch/create_github_release/test_coverage)
 
-Create a GitHub release for a new gem version.
+A script to manage your gem version and create a GitHub branch, PR, and release
+for a new gem version.
 
-The `create-github-release` script does the following:
+Since this script builds a changelog by listing the commits on the default branch,
+it works best if you are disciplined about squashing PR commits to the
+minimum number of commits necessary (usually one) in order to avoid a noisy changelog.
 
-* Bumps the project's version
-* Updates the project's changelog
-* Creates a release branch
-* Commits the version change and changelog update
-* Creates a version tag
-* Pushes the release branch to GitHub
-* Creates a GitHub release and GitHub pull request for the release
+Tested on Ruby 2.7+
 
-You should merge the pull request once it is reviewed and approved.
+* [The create\_github\_release Gem](#the-create_github_release-gem)
+  * [Installation](#installation)
+  * [Usage](#usage)
+    * [First release using this script when there were NO prior releases](#first-release-using-this-script-when-there-were-no-prior-releases)
+    * [First release using this script when there were prior releases](#first-release-using-this-script-when-there-were-prior-releases)
+    * [Subsequent releases using this script](#subsequent-releases-using-this-script)
+  * [After Running create-github-release](#after-running-create-github-release)
+  * [How the changelog is updated](#how-the-changelog-is-updated)
+  * [Limitations](#limitations)
+  * [Development](#development)
+  * [Contributing](#contributing)
+  * [License](#license)
 
-Pull the changes from the default branch and publish your gem with the `rake release` command.
+## Installation
+
+Add `create_github_release` as a development dependency in your project's gemspec:
+
+```ruby
+spec.add_development_dependency 'create_github_release', '~> 0.1'
+```
+
+and then install using `bundle update`.
+
+## Usage
 
-Here is the command line --help output:
+This gem installs the `create-guthub-release` command line tool:
 
 ```text
 Usage:
 create-github-release --help | RELEASE_TYPE [options]
 
-RELEASE_TYPE must be 'major', 'minor', or 'patch'
+RELEASE_TYPE must be 'major', 'minor', 'patch', or 'first'
 
 Options:
         --default-branch=BRANCH_NAME Override the default branch
@@ -43,27 +61,216 @@ Options:
     -h, --help                       Show this message
 ```
 
-The following conditions must be met in order to create a release:
+The RELEASE_TYPE should follow [Semantic Versioning](https://semver.org) rules:
 
-* The bundle must be up to date (via bundle update)
-* You current directory must be in the top level of the git repository
-* The default branch must be checked out
-* There are no uncommitted changes
-* The local and remote must be on the same commit
-* The last release tag must exist
-* The new release tag must not already exist either locally or remotely
-* The new release branch must not already exist either locally or remotely
-* The gh command must be installed
+* A **major** release includes incompatible API changes
+* A **minor** release includes added functionality in a backwards compatible manner
+* A **patch** release includes backwards compatible bug fixes or other inconsequential changes
 
-## Installation
+This script will be used for three different use cases:
 
-Add `create_github_release` as a development dependency in your project's gemspec:
+### First release using this script when there were NO prior releases
 
-```ruby
-spec.add_development_dependency 'create_github_release', '~> 0.1'
+If this is to be the first release of this gem follow these instructions.
+
+For this use case, let's assume the following:
+
+* the default branch is `main` (this is the HEAD branch returned by `git remote show origin`)
+* the current version of the gem is `0.1.0` (as returned by `bump current`)
+
+If a different first version number is desired, update the version number in the
+source code making sure that `bump current` returns the desired version number.
+Then commit the change to the default branch on the remote before running this
+script.
+
+You should start with a CHANGELOG.md that just has frontmatter. An empty file or
+no file is also acceptable. It is not recommended to go with the CHANGELOG.md generated
+by `bundle gem`. Here are suggested CHANGELOG.md contents prior to the first release:
+
+```markdown
+# Change Log
+
+Changes for each release are listed in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/) for its releases.
 ```
 
-and then install using `bundle update`.
+See [How the changelog is updated](#how-the-changelog-is-updated) for more information.
+
+The following prerequisites are checked by this script:
+
+* The current directory must be in the top level of the git repository
+* The HEAD commit of the default branch (`main`) must be checked out
+* The HEAD commit of the default branch of the local repository must match the
+  HEAD commit of the default branch of the remote repository
+* There are no uncommitted or unstaged changes
+* The bundle must be up to date (the script will attempt to update the bundle if needed)
+* The next-release tag (`v0.1.0`) must NOT already exist
+* The next-release branch (`release-v0.1.0`) must NOT already exist
+* The gh command must be installed and authenticated via `gh auth`
+
+You should run:
+
+```shell
+create-github-release first
+```
+
+The `create-github-release` script will do the following:
+
+* Determine the next-release version (`v0.1.0`) using `bump current`
+* Update the project's changelog file `CHANGELOG.md`
+* Create a release branch `release-v0.1.0`
+* Commit the changes to the changelog and create a release tag (`v0.1.0`) pointing
+  to that commit
+* Push the release branch to GitHub
+* Create a GitHub release and pull request for the release
+
+See [After running create-github-release](#after-running-create-github-release)
+for instructions for completing your release.
+
+### First release using this script when there were prior releases
+
+In order to start using `create-github-release` after you have used some other
+method for managing the gem version and creating releases, you need to ensure the
+following prerequisites are met:
+
+1. that `bump current` is the version of the last release (let's use `1.3.1` as an
+   example).
+2. that there is a corresponding release tag that points to the last commit on the
+   default branch of the previous release. If the last version was `1.3.1`, then
+   the last-release tag should be `v1.3.1`.
+
+Changes to the changelog file to ensure the next-release description is added correctly
+may need to be done. See [How the changelog is updated](#how-the-changelog-is-updated)
+for details.
+
+Any changes needed to make sure these prerequisites are met should merged or pushed
+to the default branch on the remote.
+
+Once these prerequisites are met and any adjustments have been done, follow the
+directions in [Subserquent releases using this script](#subsequent-releases-using-this-script).
+
+See [After running create-github-release](#after-running-create-github-release)
+for instructions for completing your release.
+
+### Subsequent releases using this script
+
+For this use case, let's assume the following:
+
+* you want to create a `major` release
+* the default branch is `main` (this is the HEAD branch returned by `git remote show origin`)
+* the current version of the gem is `0.1.0` (as returned by `bump current`)
+
+The following prerequisites must be met:
+
+* The current directory must be in the top level of the git repository
+* The HEAD commit of the default branch (`main`) must be checked out
+* The HEAD commit of the default branch of the local repository must match the
+  HEAD commit of the default branch of the remote repository
+* There are no uncommitted or unstaged changes
+* The bundle must be up to date (the script will attempt to update the bundle if needed)
+* The last-release tag (`v0.1.0`) must already exist
+* The next-release tag (`v1.0.0`) must NOT already exist
+* The next-release branch (`release-v1.0.0`) must NOT already exist
+* The gh command must be installed and authenticated via `gh auth`
+
+You should run:
+
+```shell
+create-github-release major
+```
+
+The `create-github-release` script will do the following:
+
+* Determine the last-release version using `bump current`
+* Determine the next-release version using `bump show-next RELEASE_TYPE`
+* Bump the project's version using `bump RELEASE_TYPE`
+* Update the project's changelog file `CHANGELOG.md`
+* Create a release branch `release-v1.0.0`
+* Commit the changes to the version and changelog AND create a release tag (`v1.0.0`) pointing
+  to that commit
+* Push the release branch to GitHub
+* Create a GitHub release and pull request for the release
+
+See [After running create-github-release](#after-running-create-github-release)
+for instructions for completing your release.
+
+## After Running create-github-release
+
+If you want to make additional updates to the ChangeLog or make changes as
+part of the release PR, it is best to do them before running this script. If
+you must make changes after running this script, you should do so in additional
+commits on the release branch. Before merging to the default branch, you should
+squash all commits down to ONE commit on the release branch and make sure that
+the new release tag (`v1.0.0` in this example) points to this commit.
+
+If you are happy with the PR, you should approve it in GitHub.
+
+Next, merge the release branch into the default branch **MANUALLY AT THE COMMAND
+LINE** using a fast forward merge with the following commands:
+
+```shell
+git checkout main
+git merge --ff-only release-v1.0.0
+git push
+```
+
+GitHub will automatically close the PR after the `git push` command. These commands
+are output by `create-github-release` so you do not have to memorize them ;)
+
+It is important to use a fast foward marge to ensure that the release tag points
+to the right commit after the merge. GitHub does not allow fast forward merges when
+ merging a PR.
+
+Finally, publish your gem to rubygems.org with the `rake release` command.
+
+## How the changelog is updated
+
+A release description is generated by listing the commits between the last release
+and the next release.
+
+As an example, let's assume the following:
+
+* the last release version was `0.1.0`
+* the next release version will be `1.0.0`
+* there were two changes in the next release:
+  * The first commit has sha `1111111` and a commit message starting with the
+    line 'Add feature 1'
+  * The second commit has sha `2222222` and a commit message starting with the
+    line 'Add feature 2'
+
+The release description will look like this:
+
+```text
+## Release v1.0.0
+
+Full Changelog
+
+Changes since v0.1.0:
+
+* 2222222 Add feature 2
+* 1111111 Add feature 1
+```
+
+The existing changelog file is read and split into two parts: front matter and
+body.
+
+The front matter is everything before the first markdown H2 header. If there is
+no H2 header, the entire file is considered front matter.
+
+The body is everything else in the file (if the file contains an H2 header)
+
+The resulting updated changelog file has the following sections:
+
+1. front matter
+2. next release description
+3. body (including past release descriptions)
+
+## Limitations
+
+* Does not work on Windows
+* Has only been tested on MRI Ruby
+*
 
 ## Development
 

data/create_github_release.gemspec

@@ -8,8 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors = ['James']
   spec.email = ['jcouball@yahoo.com']
 
-  spec.summary = 'Create a GitHub release PR for a Ruby Gem'
-  spec.description = spec.summary
+  spec.summary = 'A script to create a GitHub release for a Ruby Gem'
+  spec.description = <<~DESCRIPTION
+    A script that manages your gem version and creates a GitHub branch, PR, and
+    release for a new gem version.
+  DESCRIPTION
   spec.homepage = 'https://github.com/main-branch/create_github_release'
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 2.7.0'

data/lib/create_github_release/assertions/last_release_tag_exists.rb

@@ -29,6 +29,8 @@ module CreateGithubRelease
       # @raise [SystemExit] if the assertion fails
       #
       def assert
+        return if project.first_release?
+
         print "Checking that last release tag '#{project.last_release_tag}' exists..."
 
         tags = `git tag --list "#{project.last_release_tag}"`.chomp

data/lib/create_github_release/command_line_options.rb

@@ -8,7 +8,7 @@ module CreateGithubRelease
   # An array of the valid release types
   # @return [Array<String>]
   # @api private
-  VALID_RELEASE_TYPES = %w[major minor patch].freeze
+  VALID_RELEASE_TYPES = %w[major minor patch first].freeze
 
   # Regex pattern for a [valid git reference](https://git-scm.com/docs/git-check-ref-format)
   # @return [Regexp]
@@ -34,7 +34,7 @@ module CreateGithubRelease
   ) do
     # @attribute release_type [rw] the type of release to create
     #
-    #   Must be one of 'major', 'minor', or 'patch'
+    #   Must be one of the VALID_RELEASE_TYPES
     #
     #   @example
     #     options = CreateGithubRelease::CommandLineOptions.new(release_type: 'major')

data/lib/create_github_release/project.rb

@@ -22,7 +22,8 @@ module CreateGithubRelease
     #
     # The recommended way to set the attributes is to use method 2 to override values
     # and otherwise method 3 to use the default value. Method 1 is only recommended for testing
-    # or if there is no other way to accomplish what you need.
+    # or if there is no other way to accomplish what you need. Method 1 should ONLY be
+    # used in the block passed to the initializer.
     #
     # @example calling `.new` without a block
     #   options = CreateGithubRelease::CommandLineOptions.new { |o| o.release_type = 'minor' }
@@ -45,6 +46,8 @@ module CreateGithubRelease
     def initialize(options)
       @options = options
       yield self if block_given?
+
+      setup_first_release if release_type == 'first'
     end
 
     # @!attribute options [r]
@@ -65,7 +68,9 @@ module CreateGithubRelease
       :last_release_tag, :last_release_version, :release_branch, :release_log_url,
       :release_type, :release_url, :remote, :remote_base_url, :remote_repository, :remote_url,
       :changelog_path, :changes, :next_release_description, :last_release_changelog,
-      :next_release_changelog, :verbose, :quiet
+      :next_release_changelog, :first_commit, :verbose, :quiet
+
+    # attr_writer :first_release
 
     # @!attribute [rw] default_branch
     #
@@ -206,12 +211,7 @@ module CreateGithubRelease
     # @api public
     #
     def next_release_version
-      @next_release_version ||= options.next_release_version || begin
-        output = `bump show-next #{release_type}`
-        raise 'Could not determine next version using bump' unless $CHILD_STATUS.success?
-
-        output.lines.last.chomp
-      end
+      @next_release_version ||= options.next_release_version || bump_show_next_version
     end
 
     # @!attribute [rw] last_release_tag
@@ -237,7 +237,7 @@ module CreateGithubRelease
     # @api public
     #
     def last_release_tag
-      @last_release_tag ||= "v#{last_release_version}"
+      @last_release_tag ||= (first_release? ? '' : "v#{last_release_version}")
     end
 
     # @!attribute [rw] last_release_version
@@ -262,12 +262,7 @@ module CreateGithubRelease
     # @api public
     #
     def last_release_version
-      @last_release_version ||= options.last_release_version || begin
-        output = `bump current`
-        raise 'Could not determine current version using bump' unless $CHILD_STATUS.success?
-
-        output.lines.last.chomp
-      end
+      @last_release_version ||= options.last_release_version || bump_current_version
     end
 
     # @!attribute [rw] release_branch
@@ -321,7 +316,11 @@ module CreateGithubRelease
     # @api public
     #
     def release_log_url
-      @release_log_url ||= URI.parse("#{remote_url}/compare/#{last_release_tag}..#{next_release_tag}")
+      @release_log_url ||= begin
+        from = first_release? ? first_commit : last_release_tag
+        to = next_release_tag
+        URI.parse("#{remote_url}/compare/#{from}..#{to}")
+      end
     end
 
     # @!attribute [rw] release_type
@@ -536,7 +535,9 @@ module CreateGithubRelease
     #
     def changes
       @changes ||= begin
-        command = "git log 'HEAD' '^#{last_release_tag}' --oneline --format='format:%h\t%s'"
+        tip = "'HEAD'"
+        base = first_release? ? '' : "'^#{last_release_tag}' "
+        command = "git log #{tip} #{base}--oneline --format='format:%h\t%s'"
         git_log = `#{command}`
         raise "Could not determine changes since #{last_release_tag}" unless $CHILD_STATUS.success?
 
@@ -573,15 +574,18 @@ module CreateGithubRelease
     # @api public
     #
     def next_release_description
-      @next_release_description ||= <<~DESCRIPTION
-        ## #{next_release_tag} (#{next_release_date.strftime('%Y-%m-%d')})
+      @next_release_description ||= begin
+        header = first_release? ? 'Changes:' : "Changes since #{last_release_tag}:"
+        <<~DESCRIPTION
+          ## #{next_release_tag} (#{next_release_date.strftime('%Y-%m-%d')})
 
-        [Full Changelog](#{release_log_url})
+          [Full Changelog](#{release_log_url})
 
-        Changes since #{last_release_tag}:
+          #{header}
 
-        #{list_of_changes}
-      DESCRIPTION
+          #{list_of_changes}
+        DESCRIPTION
+      end
     end
 
     # @!attribute [rw] last_release_changelog
@@ -689,6 +693,7 @@ module CreateGithubRelease
     #
     def to_s
       <<~OUTPUT
+        first_release: #{first_release}
         default_branch: #{default_branch}
         next_release_tag: #{next_release_tag}
         next_release_date: #{next_release_date}
@@ -758,8 +763,84 @@ module CreateGithubRelease
 
     alias quiet? quiet
 
+    # @!attribute [rw] last_release_changelog
+    #
+    # true if release_type is 'first' otherwise false
+    #
+    # @example Returns true if release_type is 'first'
+    #   options = CreateGithubRelease::CommandLineOptions.new(release_type: 'first')
+    #   project = CreateGithubRelease::Project.new(options)
+    #   project.first_release? #=> true
+    #
+    # @example Returnss false if release_type is not 'first'
+    #   options = CreateGithubRelease::CommandLineOptions.new(release_type: 'major')
+    #   project = CreateGithubRelease::Project.new(options)
+    #   project.first_release? #=> false
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    #
+    def first_release
+      @first_release ||= release_type == 'first'
+    end
+
+    alias first_release? first_release
+
+    # @!attribute [rw] first_commit
+    #
+    # The SHA of the oldest commit that is an ancestor of HEAD
+    #
+    # @example
+    #   options = CreateGithubRelease::CommandLineOptions.new(release_type: 'major')
+    #   project = CreateGithubRelease::Project.new(options)
+    #   project.first_commit? #=> '1234567'
+    #
+    # @return [String]
+    #
+    # @api public
+    #
+    def first_commit
+      @first_commit ||= begin
+        command = "git log 'HEAD' --oneline --format='format:%h'"
+        git_log = `#{command}`
+        raise "Could not list changes from first commit up to #{last_release_tag}" unless $CHILD_STATUS.success?
+
+        git_log.split("\n").last.chomp
+      end
+    end
+
     private
 
+    # The current version of the project as determined by bump
+    # @return [String] The current version of the project
+    # @api private
+    def bump_current_version
+      output = `bump current`
+      raise 'Could not determine current version using bump' unless $CHILD_STATUS.success?
+
+      output.lines.last.chomp
+    end
+
+    # The next version of the project as determined by bump and release_type
+    # @return [String] The next version of the project
+    # @api private
+    def bump_show_next_version
+      output = `bump show-next #{release_type}`
+      raise 'Could not determine next version using bump' unless $CHILD_STATUS.success?
+
+      output.lines.last.chomp
+    end
+
+    # Setup versions and tags for a first release
+    # @return [Void]
+    # @api private
+    def setup_first_release
+      self.next_release_version = @next_release_version || bump_current_version
+      self.last_release_version = ''
+      self.last_release_tag = ''
+    end
+
     # The list of changes in the release as a string
     # @return [String] The list of changes in the release as a string
     # @api private

data/lib/create_github_release/tasks/update_version.rb

@@ -30,11 +30,38 @@ module CreateGithubRelease
       # @raise [SystemExit] if the task fails
       #
       def run
+        return if project.first_release?
+
         print 'Updating version...'
-        message, result = Bump::Bump.run(project.release_type, commit: false)
-        error "Could not bump version: #{message}" unless result.zero?
+        bump_version
+        stage_version_file
+      end
+
+      private
+
+      # Update the version using bump
+      # @return [void]
+      # @api private
+      def bump_version
+        `bump #{project.release_type} --no-commit`
+        error 'Could not bump version' unless $CHILD_STATUS.success?
+      end
+
+      # Return the path the the version file using bump
+      # @return [String]
+      # @api private
+      def bump_version_file
+        output = `bump file`
+        error 'Bump could determine the version file' unless $CHILD_STATUS.success?
 
-        version_file = Bump::Bump.file
+        output.lines.last.chomp
+      end
+
+      # Identify the version file using bump and stage the change to it
+      # @return [void]
+      # @api private
+      def stage_version_file
+        version_file = bump_version_file
         `git add "#{version_file}"`
         if $CHILD_STATUS.success?
           puts 'OK'

data/lib/create_github_release/version.rb

@@ -2,5 +2,5 @@
 
 module CreateGithubRelease
   # The version of this gem
-  VERSION = '0.3.0'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: create_github_release
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - James
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-01-30 00:00:00.000000000 Z
+date: 2023-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bump
@@ -178,7 +178,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: Create a GitHub release PR for a Ruby Gem
+description: |
+  A script that manages your gem version and creates a GitHub branch, PR, and
+  release for a new gem version.
 email:
 - jcouball@yahoo.com
 executables:
@@ -258,8 +260,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
-summary: Create a GitHub release PR for a Ruby Gem
+summary: A script to create a GitHub release for a Ruby Gem
 test_files: []