semmy 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e37930e9fb640ca1d09d44ad75a455267528fdcb
-  data.tar.gz: d9b8a83c5b32ed68a8409b40107709676ec24aef
+  metadata.gz: e2863f4f726ca7e693eb807b85361216b13d6888
+  data.tar.gz: 25ea8f2c9cd7e1800e6b5aac5b183df255d2d8ef
 SHA512:
-  metadata.gz: 97963c7d57e85aa7f04d94f0fbb9c3def74e5a387163f390e0764b8cff55ed2762693d3bafded2206f2fa5a5666c58b0a9a73eae1b27f3492e62a0adeb09c0ce
-  data.tar.gz: bf42378f8c9817d88923613b9daab2c37fb96fae91ca1a262cc3f39fb9e3b2c58be477d6e758b04ddd4288e87ca26a761088431837422b015d467cca5fb17c5f
+  metadata.gz: 1182968ffa50bdc64b6023186cf8ef994dab8aa39c61c408a2822c2e07163860bba9f3b987911b47f613fb93eb61fb0267a104bbf7c10b03425d08a05501d4e2
+  data.tar.gz: e2fd0ec272420a10a2e4e8f2698e5120986eccec10b8c311b703a88ef1cf6e0402cf5c6187cfebb21669a178abf72b3cd8cc84006ab11455b4ede10e16cd9704

data/CHANGELOG.md

@@ -1,34 +1,28 @@
 # CHANGELOG
 
-### Version 0.4.0
+### Version 1.0.0
 
 2017-07-13
 
-[Compare changes](https://github.com/tf/semmy/compare/0-3-stable...v0.4.0)
+[Compare changes](https://github.com/tf/semmy/compare/0-x-stable...v1.0.0)
 
-- Only keep sections for current minor version in changelog and link
-  to previous stable branch.
-- Compare minor versions to previous stable branch.
+##### Breaking Changes
 
-### Version 0.3.0
+- A typo in the name of the `changelog_unreleased_section_heading` and
+  `changelog_unreleased_section_blank_slate` options was fixed.
+- The default value of `changelog_unreleased_section_heading` changed
+  to "Unreleased Changes". You need to update the header in your
+  changelog or manually set the previous value via the configuration option.
 
-2016-09-09
+##### New Features
 
-[Compare changes](https://github.com/tf/semmy/compare/v0.2.0...v0.3.0)
+- Add `bump:patch` task which begins a patch level release.
+- Add `bump:mahor` task which updates the major version.
 
-- Fix default GitHub compare url.
-- Add link comparing to last patch level for stable release.
+##### Bug Fixes
 
-### Version 0.2.0
+- Fix indentation of generated unreleased changes section.
 
-2016-06-09
-
-[Compare changes](https://github.com/tf/semmy/compare/v0.1.0...v0.2.0)
-
-- Fine tune default commit messages.
-
-### Version 0.1.0
-
-2016-06-09
-
-- Initial release
+See
+[0-x-stable branch](https://github.com/tf/semmy/blob/0-x-stable/CHANGELOG.md)
+for previous changes.

data/README.md

@@ -9,12 +9,52 @@
 An opinionated set of rake tasks to maintain gems following semantic
 versioning principles.
 
+## Assumptions
+
+### Git Branches and Tags
+
+Development happens directly on `master` or by merging pull
+requests. When a release is made, a stable branch called `x-y-stable`
+is created. Semmy relies on Bundler's `release` task to create version
+tags.
+
+Patch level versions are released via backports to the stable
+branches.
+
+### Version Suffix
+
+The version in the gem's version file is increased in a separate
+commit right after release. The version always has an `dev` suffix
+(i.e. `1.1.0.dev`), which is only removed in the last commit
+preparing the release. That way it is easy to see in a project's
+`Gemfile.lock` whether an unreleased version is used.
+
+Patch level versions are expected to be released immediately after
+backporting bug fixes. So there are never commits with a version
+suffix on stable branches.
+
+### Doc Tags
+
+Pull requests introducing new features, are expected to markup new
+code elements with a `@since edge` doc tag. When a release is
+prepared, `edge` is replaced with the current version string. That way
+pull request authors do not have to guess, which version will merge
+their commits.
+
+### Changelog
+
+Unreleased changes are listed in a section at the top. When preparing
+a release this section is closed by placing a version heading above it
+and inserting a compare link. Changelog entries for patch level
+versions are only committed on the stable branches since they only
+backport bug fixes from master.
+
 ## Installation
 
 Add development dependency to your gemspec:
 
     # your.gemspec
-    s.add_development_dependency 'semmy', '~> 0.2'
+    s.add_development_dependency 'semmy', '~> 1.0'
 
 Install gems:
 
@@ -35,10 +75,11 @@ Semmy defines a new task to prepare a release:
 
 This task:
 
-* Removes the `dev` version suffix from the version file
-* Rewrites doc tags
+* Ensures the gem can be installed.
+* Removes the `dev` version suffix from the version file.
+* Rewrites doc tags.
 * Closes the section of the new version in the changelog.
-* Commits the changes
+* Commits the changes.
 
 It is expected that a `release` task exists. Normally this tasks is
 provided by Bundler.
@@ -48,67 +89,91 @@ provided by Bundler.
 Semmy registers additional actions which shall be
 executed right after the release:
 
-* Creates a stable branch
+* Creates a stable branch.
 * Bumps the version to the next minor version with `alpha` version
   suffix.
-* Inserts an "Changes on master" section in the changelog.
+* Inserts an "Unreleased Changes" section in the changelog.
 
-## Assumptions
+The resulting commit graph looks like:
 
-### Git Branches and Tags
+    * (master) Bump version to 1.3.0.dev
+    * (v1.2.0, 1-2-stable) Prepare 1.2.0 release
+    * Some new feature
 
-Development happens directly on `master` or by merging pull
-requests. When a release is made, a stable branch called `x-y-stable`
-is created. Semmy relies on Bundler's `release` task to create version
-tags.
+### Releasing a Patch Level Version
 
-Patch level versions are released via backports to the stable
-branches.
+Assume an important bug fix has been added to `master`:
 
-### Version Suffix
+    * (master) Important bug fix
+    * First new feature
+    * Bump version to 1.3.0.dev
+    * (v1.0.0, 1-2-stable) Prepare 1.2.0 release
 
-The version in the gem's version file is increased in a separate
-commit right after release. The version always has an `alpha` suffix
-(i.e. `1.1.0.alpha`), which is only removed in the last commit
-preparing the release. That way it is easy to see in a project's
-`Gemfile.lock` whether an unreleased version is used.
+check out the stable branch and cherry pick commits:
 
-Patch level versions are expected to be released immediately after
-backporting bug fixes. So there are never commits with a version
-suffix on stable branches.
+    $ git checkout 1-2-stable
+    $ git cherry-pick master
 
-### Doc Tags
+Then run:
 
-Pull requests introducing new features, are expected to markup new
-code elements with a `@since edge` doc tag. When a release is
-prepared, `edge` is replaced with the current version string. That way
-pull request authors do not have to guess, which version will merge
-their commits.
+    $ rake bump:patch
 
-### Changelog
+This task:
 
-Unreleased changes are listed in a section at the top. When preparing
-a release this section is closed by placing a version heading above it
-and inserting a compare link. Changelog entries for patch level
-versions are only committed on the stable branches since they only
-backport bug fixes from master.
+* Bumps the version to `1.2.1` in the version file.
+* Inserts an "Unreleased Changes" section in the changelog.
 
-## Example Life Cycle
+Add items to the new changelog section, then run:
 
-### Releasing a Minor Version
+    $ rake release:prepare
 
-     1:  * (master) Other important bug fix
-     2:  * Minor bug fix
-     3:  * First new feature
-     4:  * Important bug fix
-     5:  * Begin work on 1.1
-     6:  | * (1-0-stable, v1.0.2) Prepare 1.0.2 release
-     7:  | * Backport of other bug fix
-     8:  | * (v1.0.1) Prepare 1.0.1 release
-     9:  | * Backport of important bug fix
-    10:  |/
-    11:  * (v1.0.0) Prepare 1.0.0 release
+This task detects that we are currently on a stable branch and
+performs the following subset of the normal prepare tasks:
 
-### Releasing a Patch Level Version
+* Closes the section of the new version in the changelog.
+* Commits the changes
+
+You can now run `rake release`, leaving you with the following commit
+graph:
+
+    * (master) Important bug fix
+    * First new feature
+    * Bump version to 1.3.0.dev
+    | * (v1.2.1, 1-2-stable) Prepare 1.2.1 release
+    | * Important bug fix
+    |/
+    * (v1.2.0) Prepare 1.2.0 release
+
+### Releasing a Major Version
+
+If breaking changes have been merged to master, run:
+
+    $ rake bump:major
+
+Assuming the version was `1.2.0.dev` before, This bumps the major
+version in the version file to `2.0.0.dev` and updates the changelog
+to reference `1-x-stable` for comparison.
+
+The branch `1-x-stable` has to be created and managed manually. It
+should always point to the same commit as the lastest minor version
+stable branch of the major version.
+
+The rest of the release can be performed like a normal minor version
+release.
+
+## 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. Run `bin/rspec` to execute the test
+suite.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/tf/semmy.
 
+## License
 
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).

data/lib/semmy/changelog.rb

@@ -22,7 +22,7 @@ module Semmy
       private
 
       def unreleased_section_matcher
-        /#{config.changelog_unrelased_section_heading}(\s*#{compare_link_matcher})?/
+        /#{config.changelog_unreleased_section_heading}(\s*#{compare_link_matcher})?/
       end
 
       def compare_link_matcher
@@ -72,7 +72,7 @@ module Semmy
 
     UpdateForMinor = Struct.new(:config, :options) do
       def call(contents)
-        replace_starting_at(version_line_matcher,
+        replace_starting_at(Changelog.version_line_matcher(config),
                             contents,
                             unreleased_section)
       end
@@ -80,15 +80,26 @@ module Semmy
       private
 
       def unreleased_section
-        <<-END.unindent
-          #{config.changelog_unrelased_section_heading}
-
-          #{compare_link_for_master}
-
-          #{config.changelog_unrelased_section_blank_slate}
-
-          #{link_to_changelog_on_previous_minor_stable_branch}
-        END
+        # Once Ruby < 2.3 support is dropped, this can be rewritten
+        # as:
+        #
+        #     <<~END
+        #       #{config.changelog_unreleased_section_heading}
+        #
+        #       #{compare_link_for_master}
+        #
+        #       #{config.changelog_unreleased_section_blank_slate}
+        #
+        #       #{link_to_changelog_on_previous_minor_stable_branch}
+        #     END
+        #
+        # `unindent` cannot handle line breaks in interpolated values correctly.
+        [
+          config.changelog_unreleased_section_heading,
+          compare_link_for_master,
+          config.changelog_unreleased_section_blank_slate,
+          link_to_changelog_on_previous_minor_stable_branch
+        ].join("\n\n") << "\n"
       end
 
       def compare_link_for_master
@@ -112,12 +123,6 @@ module Semmy
                                                   config.stable_branch_name)
       end
 
-      def version_line_matcher
-        Regexp.new(config.changelog_version_section_heading % {
-                     version: '([0-9.]+)'
-                   })
-      end
-
       def replace_starting_at(line_matcher, text, inserted_text)
         unless text =~ line_matcher
           fail(InsertPointNotFound, 'Insert point not found.')
@@ -127,10 +132,52 @@ module Semmy
       end
     end
 
+    InsertUnreleasedSection = Struct.new(:config) do
+      def call(contents)
+        insert_before(Changelog.version_line_matcher(config),
+                      contents,
+                      config.changelog_unreleased_section_heading << "\n")
+      end
+
+      private
+
+      def insert_before(line_matcher, text, inserted_text)
+        text.dup.tap do |result|
+          unless (result.sub!(line_matcher, inserted_text + "\n\\0"))
+            fail(InsertPointNotFound,
+                 'Insert point not found.')
+          end
+        end
+      end
+    end
+
+    ReplaceMinorStableBranchWithMajorStableBranch = Struct.new(:config, :options) do
+      def call(contents)
+        contents.gsub(minor_stable_branch(options[:version]),
+                      major_stable_branch(options[:version]))
+      end
+
+      private
+
+      def minor_stable_branch(version)
+        VersionString.previous_stable_branch_name(version, config.stable_branch_name)
+      end
+
+      def major_stable_branch(version)
+        config.stable_branch_name % VersionString.components(version).merge(minor: 'x')
+      end
+    end
+
     def version_tag(version)
       "v#{version}"
     end
 
+    def version_line_matcher(config)
+      Regexp.new(config.changelog_version_section_heading % {
+                   version: '([0-9.]+)'
+                 })
+    end
+
     def compare_link(config, interpolations)
       "[Compare changes](#{compare_url(config, interpolations)})"
     end

data/lib/semmy/configuration.rb

@@ -14,8 +14,8 @@ module Semmy
 
     attr_accessor :changelog_path
     attr_accessor :changelog_version_section_heading
-    attr_accessor :changelog_unrelased_section_heading
-    attr_accessor :changelog_unrelased_section_blank_slate
+    attr_accessor :changelog_unreleased_section_heading
+    attr_accessor :changelog_unreleased_section_blank_slate
     attr_accessor :changelog_previous_changes_link
 
     attr_accessor :source_files_with_docs_tags
@@ -34,8 +34,8 @@ module Semmy
 
       @changelog_path = 'CHANGELOG.md'
       @changelog_version_section_heading = '### Version %{version}'
-      @changelog_unrelased_section_heading = '### Changes on `master`'
-      @changelog_unrelased_section_blank_slate = 'None so far.'
+      @changelog_unreleased_section_heading = '### Unreleased Changes'
+      @changelog_unreleased_section_blank_slate = 'None so far.'
       @changelog_previous_changes_link = "See\n[%{branch} branch](%{url})\nfor previous changes."
 
       @source_files_with_docs_tags = '{app,lib}/**/*.{js,rb,scss}'

data/lib/semmy/tasks.rb

@@ -66,6 +66,16 @@ module Semmy
       task 'release' do
         Rake.application['release:after'].invoke
       end
+
+      task 'bump:patch' => [
+        'semmy:versioning:bump_patch_level',
+        'semmy:changelog:insert_unreleased_section'
+      ]
+
+      task 'bump:major' => [
+        'semmy:changelog:replace_minor_stable_branch_with_major_stable_branch',
+        'semmy:versioning:bump_major'
+      ]
     end
   end
 end

data/lib/semmy/tasks/changelog_sections.rb

@@ -26,6 +26,23 @@ module Semmy
                                                         version: Project.version,
                                                         homepage: Gemspec.homepage))
           end
+
+          task 'replace_minor_stable_branch_with_major_stable_branch' do
+            Shell.info('Updating changelog ' \
+                       "in #{config.changelog_path}.")
+
+            Files.rewrite(config.changelog_path,
+                          Changelog::ReplaceMinorStableBranchWithMajorStableBranch
+                            .new(config, version: Project.version))
+          end
+
+          task 'insert_unreleased_section' do
+            Shell.info('Inserting unreleased changes header ' \
+                       "in #{config.changelog_path}.")
+
+            Files.rewrite(config.changelog_path,
+                          Changelog::InsertUnreleasedSection.new(config))
+          end
         end
       end
     end

data/lib/semmy/tasks/versioning.rb

@@ -13,6 +13,15 @@ module Semmy
             rewrite_gemspec_version(new_version)
           end
 
+          task 'bump_major' do
+            new_version = VersionString
+              .bump_major(Project.version, config.development_version_suffix)
+
+            Shell.info("Bumping version to #{new_version}.")
+
+            rewrite_gemspec_version(new_version)
+          end
+
           task 'bump_minor' do
             new_version = VersionString
               .bump_minor(Project.version, config.development_version_suffix)
@@ -21,6 +30,15 @@ module Semmy
 
             rewrite_gemspec_version(new_version)
           end
+
+          task 'bump_patch_level' do
+            new_version = VersionString
+              .bump_patch_level(Project.version)
+
+            Shell.info("Bumping version to #{new_version}.")
+
+            rewrite_gemspec_version(new_version)
+          end
         end
       end
 

data/lib/semmy/version.rb

@@ -1,3 +1,3 @@
 module Semmy
-  VERSION = '0.4.0'
+  VERSION = '1.0.0'
 end

data/lib/semmy/version_string.rb

@@ -18,18 +18,16 @@ module Semmy
       new_version
     end
 
-    def bump_minor(version, suffix)
-      components = version.split('.')
-
-      unless components.last =~ /^[0-9]+$/
-        fail(UnexpectedSuffix, "Expected a version without suffix, found #{version}.")
-      end
+    def bump_major(version, suffix)
+      [bump(0, version), suffix].join('.')
+    end
 
-      components.map!(&:to_i)
-      components[1] += 1
-      components << suffix
+    def bump_minor(version, suffix)
+      [bump(1, version), suffix].join('.')
+    end
 
-      components.join('.')
+    def bump_patch_level(version)
+      bump(2, version)
     end
 
     def minor_only(version)
@@ -70,17 +68,30 @@ module Semmy
 
     private
 
+    def bump(component_index, version)
+      components = version.split('.')[0..2].map!(&:to_i)
+
+      [
+        components[0...component_index],
+        components[component_index] + 1,
+        [0] * (2 - component_index)
+      ].flatten.join('.')
+    end
+
     def previous_minor_version_components(version)
       components = version.split('.').map(&:to_i)
 
       if components[1].zero?
-        fail(NoPreviousMinor, "Cannot get previous minor version of #{version}.")
+        {
+          major: components[0] - 1,
+          minor: 'x'
+        }
+      else
+        {
+          major: components[0],
+          minor: components[1] - 1
+        }
       end
-
-      {
-        major: components[0],
-        minor: components[1] - 1
-      }
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: semmy
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Tim Fischbach