branch-name 1.0.0.pre.beta → 2.0.0.pre.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7dad0772990843cd87dc265aa42d9ddd8fc91c0c50db1c8d0e7d48be3ca7129
-  data.tar.gz: 6b64ae358a4105d1495f10a5d5d4e24997ee0c45fbdb9e10135e295d3ff686ae
+  metadata.gz: 166d6b67749f23a48cca5435c6b4b923d57b9e8f4e716ff61c5765da932b686a
+  data.tar.gz: e5c041c60834c56da210d0843e0bf099e62fa21adb120f46a1d58b07793f2cbb
 SHA512:
-  metadata.gz: b90aa2baa2030cd11a7ded0189f3efc273d923e42dad82f6150b670570cf95375930948fb05aaa5a7348429e32a53f2de8a91fbc5f9dfdabf5315851c7078db4
-  data.tar.gz: ca83be22b65d2174bfb88ab3cf971306008179856557f4c39870cd427b0cbcfcda921646cb78cd51110b8b0b3eee8e97d54868f61567848fe52cb8d964962668
+  metadata.gz: 48334163ec2756cdebfd45344ec91b34e602d0b78573e52aa61418ff8915b77107513e3745cf0cd10c353cb84f669993ff0835c37b964500405c67b9b46cc9ce
+  data.tar.gz: f3ec35602f29a9edcd699383697fcb5aac3773122f9db42f82dc7748f646fa2c20bedf6fbaf0cb48d716b93a6d154ce2d5c1a5e34a657f0ea8d6c23265bff976

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    branch-name (1.0.0.pre.beta)
+    branch-name (2.0.0.pre.beta)
       activesupport (~> 7.0, >= 7.0.4)
       colorize (~> 0.8.1)
       thor (~> 1.2, >= 1.2.1)

data/README.md

@@ -1,28 +1,102 @@
-# Branch::Name
+# `branch-name`
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/branch/name`. To experiment with that code, run `bin/console` for an interactive prompt.
+`branch-name` is a gem that provides a command-line interface that allows you to accomplish several tasks, tasks I *personally* find myself having to carry out every time I work on a feature branch. I created this gem *for myself*; however, you are free to use it yourself, if any of these tasks fits into your personal routine:
+
+1. Formulate a git *feature branch name*, given a [jira](https://www.atlassian.com/software/jira) ticket and jira ticket description. **Why? Because I am constantly having to create git feature branch names that are based on jira ticket and jira ticket descriptions.**
+2. Optionally create a "project" based on the *branch name* (formulated in step 1 above). **Why? Because I'm constantly having to create folders to manage files associated with the feature branches I am working on.**
+3. Optionally use and manage default options that determine the git  feature branch name formulated, project greated, and default files associated with the project.**Why? Because I routinely have to create files to support the feature I am working on and associate them _with_ the feature I am working on. For example: scratch.rb to hold scratch code, snippets.rb to hold code to execute to perform redundant tasks, and readme.txt files to document things I need to remember.**
+
+## Caveats
+
+NOTE: This documentation assumes *macos* and any reference to `<username>` should be assumed to equal `$ whoami` unless otherwise noted.
+
+NOTE: This documentation makes reference to *cards* and/or *tickets*; these terms should be considered synonymous, and are used to refer to *user stories*, *tasks*, *bugs*, etc.: work that is normally created against a software development team's [Jira](https://www.atlassian.com/software/jira) Project board while adhering to [Agile development methodology](https://www.atlassian.com/agile#:~:text=Agile%20is%20an%20iterative%20approach,small%2C%20but%20consumable%2C%20increments.). While `branch-name` was created to be used while practicing Agile, `branch-name` can be used outside the Agile context as well.
 
-TODO: Delete this and the text above, and describe your gem
 
 ## Installation
 
-Add this line to your application's Gemfile:
+    $ gem install branch-name
+
+## Usage/Examples
 
-```ruby
-gem 'branch-name'
+### `branch-name` help
+```shell
+# Display general branch-name help
+$ branch-name help
+
+# Display help for the 'create' command
+$ branch-name help create
+
+# Display help for the 'config' command and subsommands
+$ branch-name help config
+$ branch-name config help info
+$ branch-name config help init
+$ branch-name config help delete
 ```
 
-And then execute:
+### Initialize `branch-name` configuration files
+Setting up *global* settings would be a good place to start:
+
+```
+$ branch-name config init global
+#=> Configuration file (/Users/<username>/.branch-name) created
+```
 
-    $ bundle install
+This creates a `.branch-name` .yaml configuration file the home folder of the current user (`$ whoami` on *macos*) with the following option defaults. The option defaults created will be used with their respective `branch-name` command indicated by the `branch-name` command name under which each option resides. You may manually alter any of the option values to suite your needs. To determine what options are available for each `branch-name` command, simply view help for that particular command. If a `brnch-name` command is *not* found in the `.branch-name` confg file when it is first initialized (e.g. `$ branch-name config init global #=> /Users/<username>/.branch-name`), default options for that particular `branch-name` command is not currently supported.
 
-Or install it yourself as:
+For example, the following default options will be used whenever the `branch-name create` command is executed for the user "`<username>`":
 
-    $ gem install branch-name
+```yaml
+# /Users/<username>/.branch-name
+---
+create:
+  downcase: false
+  separator: _
+  project: false
+  project_location: "/Users/<username>"
+  project_files:
+  - scratch.rb
+  - readme.txt
+  ```
 
-## Usage
+NOTE: It is recommended that you change the default `create: project_location` to a more suitable location depending on your *os*. For example, on *macos* you might want to change this to `"/Users/<username>/Documents"`, `"/Users/<username>/Documents/features"`, or something similar.
 
-TODO: Write usage instructions here
+Any or all of these options can be overwritten on the command-line:
+
+For more information:
+`$ branch-name config help init`
+
+### Creating Feature Branch Names and Projects Examples
+
+NOTE: `branch-name create` really doesn't "create" anything (unless you use the `-p` option, in which case it will create a "project" for you); rather, `branch-name create` simply formulates a suitable feature branch name given a *jira* ticket and *jira* ticket description.
+
+NOTE: The below examples will assume the following `global` config file defaults (`$ branch-name config init global`) that have been *manually* manipulated to have the following options:
+
+```yaml
+# /Users/<username>/.branch-name
+---
+create:
+  downcase: false
+  separator: _
+  project: false
+  project_location: "/Users/<username>/feature-branches/2022"
+  project_files:
+  - readme.txt
+  - scratch.rb
+  - snippets.rb
+  ```
+
+This example formulates feature a branch named *lg-12345-pay-down-tech-debt-on-user-model* by converting the ticket and ticket description to lowercase (`-d`) and delimiting the feature branch name tokens with a "-" character (`-s -`). The `-p` option instructs `branch-name create` to create the project folder */Users/<username>/feature-branches/2022/lg-12345-pay-down-tech-debt-on-user-model*. The aforementioned project folder will also contain the following files: readme.txt, scratch.rb and snippets.rb. In addition to this, `branch-name create` will also copy the feature brach name to the clipboard for you. This is convienient when you need to create a feature branch in github, or from the command-line.
+
+```shell
+$ branch-name create -p -d -s - "Pay down tech debt on User model" LG-12345
+```
+
+This example simply formulates feature a branch named *Add_create_and_destroy_session_controller_actions* and copies it to the clipboard.
+
+```shell
+$ branch-name create "Add #create and #destroy session controller actions"
+```
 
 ## Development
 

data/branch-name.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.authors      = ['Gene M. Angelo, Jr.']
   spec.email        = ['public.gma@gmail.com']
 
-  spec.summary      = 'Generates a branch name based on a JIRA card/ticket number.'
-  spec.description  = 'Generates a branch name based on a JIRA card/ticket number.'
-  spec.homepage     = 'https://github.com/gangelo/branch_name'
+  spec.summary      = 'Generates a branch name based on a JIRA ticket/ticket number.'
+  spec.description  = 'Generates a branch name based on a JIRA ticket/ticket number.'
+  spec.homepage     = 'https://github.com/gangelo/branch-name'
   spec.license      = 'MIT'
 
   spec.required_ruby_version = '>= 3.0.1'

data/lib/branch/name/cli.rb

@@ -9,7 +9,7 @@ require_relative 'configurable'
 require_relative 'exitable'
 require_relative 'loadable'
 require_relative 'locatable'
-require_relative 'nameable'
+require_relative 'normalizable'
 require_relative 'projectable'
 require_relative 'subcommands/config'
 require_relative 'version'
@@ -24,7 +24,7 @@ module Branch
       include Exitable
       include Loadable
       include Locatable
-      include Nameable
+      include Normalizable
       include Projectable
 
       class_option :debug, type: :boolean, default: false
@@ -33,21 +33,27 @@ module Branch
       default_task :create
       map %w[--version -v] => :version
 
-      desc 'create [OPTIONS] TICKET [DESCRIPTION]', 'Formulate a branch name based on a ticket and optional description'
+      desc 'create [OPTIONS] DESCRIPTION [TICKET]', 'Formulate a branch name based on a ticket
+        description and optional ticket'
       long_desc <<-LONG_DESC
         NAME
         \x5
-        `branch-name create` -- will formulate a Git branch name based on the TICKET and optional DECRIPTION provided.
+        `branch-name create` -- will formulate a Git branch name based on the
+        DESCRIPTION and optional TICKET provided.
 
         SYNOPSIS
         \x5
-        branch-name create [-d|-s|-p|-pL|-pF] TICKET [DESCRIPTION]
+        branch-name create [-l|-f|-d|-s|-p] DESCRIPTION [TICKET]
 
         \x5
         The following options are available:
 
+        \x5 NOTE: Default option values will be overidden if .branch-name config files
+        are present. Run `branch-name config info` to determine what config files
+        are present.
+
         \x5 -d: Forces the branch name to lower case.
-                The default is --no-downcase
+                The default is: #{DEFAULT_BRANCH_NAME_OPTIONS['create']['downcase']}.
 
         \x5\x5 -s SEPARATOR: Indicates the SEPARATOR that will be used to delimit tokens in the branch name.
                The default SEPARATOR is: '#{DEFAULT_BRANCH_NAME_OPTIONS['create']['separator']}'.
@@ -55,11 +61,11 @@ module Branch
         \x5\x5 -p: Indicates that a project should be created.
                The default is: #{DEFAULT_BRANCH_NAME_OPTIONS['create']['project']}.
 
-        \x5 -pF: Used with the -p option. If -pF is specified, project files
-            will be created in the PROJECT_LOCATION specified by the -pL option.
+        \x5 -f: Used with the -p option. If -f is specified, project files
+            will be created in the PROJECT_LOCATION specified by the -l option.
             The default is: #{DEFAULT_BRANCH_NAME_OPTIONS['create']['project_files']}.
 
-        \x5\x5 -pL PROJECT_LOCATION: Indicates where the project should be created.
+        \x5\x5 -l PROJECT_LOCATION: Indicates where the project should be created.
             A "project" is a folder that is created in the PROJECT_LOCATION specified,
             whose name is equivalent to the branch name that is formulated.
             The default is: "#{Locatable.project_folder(options: options)}".
@@ -67,19 +73,18 @@ module Branch
       method_option :downcase, type: :boolean, aliases: '-d'
       method_option :separator, type: :string, aliases: '-s'
       method_option :project, type: :boolean, aliases: '-p'
-      method_option :project_location, type: :string, aliases: '-pL'
-      method_option :project_files, type: :array, aliases: '-pF'
+      method_option :project_location, type: :string, aliases: '-l'
+      method_option :project_files, type: :array, aliases: '-f'
 
-      def create(ticket, ticket_description = nil)
-        if ticket.blank?
-          say_error 'ticket is required', :red
+      def create(ticket_description, ticket = nil)
+        if ticket_description.blank?
+          say_error 'description is required', :red
           exit 1
         end
 
         init_options_for! command: :create
 
-        branch_name = "#{ticket} #{ticket_description}"
-        branch_name = normalize_branch_name branch_name
+        branch_name = normalize_branch_name(ticket_description, ticket)
 
         say "Branch name: #{branch_name}", :cyan
 

data/lib/branch/name/configurable.rb

@@ -18,7 +18,7 @@ module Branch
           'separator' => '_',
           'project' => false,
           'project_location' => Locatable.project_folder,
-          'project_files' => %w[scratch.rb readme.txt]
+          'project_files' => %w[readme.txt scratch.rb snippets.rb]
         }
       }.freeze
       # rubocop:enable Style/StringHashKeys

data/lib/branch/name/normalizable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Branch
+  module Name
+    module Normalizable
+      NON_WORD_CHARS_REGEX = /[^\w]/
+
+      def normalize_branch_name(ticket_description, ticket)
+        normalized_ticket_description = normalize_ticket_description ticket_description
+        return normalized_ticket_description if ticket.blank?
+
+        normalized_ticket = normalize_ticket ticket
+        "#{normalized_ticket}#{options[:separator]}#{normalized_ticket_description}"
+      end
+
+      private
+
+      def normalize_ticket_description(ticket_description)
+        normalize_token ticket_description
+      end
+
+      def normalize_ticket(ticket)
+        ticket.split(NON_WORD_CHARS_REGEX).filter_map do |token|
+          normalize_token(token)
+        end.join(options[:separator])
+      end
+
+      def normalize_token(token)
+        token = token.strip
+          .squeeze(' ')
+          .split.join(options[:separator])
+        token = token.gsub(NON_WORD_CHARS_REGEX, '')
+        token = token.squeeze(options[:separator])
+        token = token.downcase if options[:downcase]
+        token
+      end
+    end
+  end
+end

data/lib/branch/name/projectable.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 require 'fileutils'
 require_relative 'locatable'

data/lib/branch/name/version.rb

@@ -3,6 +3,6 @@
 module Branch
   module Name
     # branch-name version
-    VERSION = '1.0.0-beta'
+    VERSION = '2.0.0-beta'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: branch-name
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.beta
+  version: 2.0.0.pre.beta
 platform: ruby
 authors:
 - Gene M. Angelo, Jr.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-18 00:00:00.000000000 Z
+date: 2022-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -64,7 +64,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.2.1
-description: Generates a branch name based on a JIRA card/ticket number.
+description: Generates a branch name based on a JIRA ticket/ticket number.
 email:
 - public.gma@gmail.com
 executables:
@@ -94,17 +94,17 @@ files:
 - lib/branch/name/exitable.rb
 - lib/branch/name/loadable.rb
 - lib/branch/name/locatable.rb
-- lib/branch/name/nameable.rb
+- lib/branch/name/normalizable.rb
 - lib/branch/name/projectable.rb
 - lib/branch/name/subcommands/config.rb
 - lib/branch/name/subcommands/init.rb
 - lib/branch/name/version.rb
 - sig/branch/name.rbs
-homepage: https://github.com/gangelo/branch_name
+homepage: https://github.com/gangelo/branch-name
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/gangelo/branch_name
+  homepage_uri: https://github.com/gangelo/branch-name
   source_code_uri: https://github.com/gangelo/branch-name
   changelog_uri: https://github.com/gangelo/branch-name/CHANGELOG.md
   rubygems_mfa_required: 'true'
@@ -126,5 +126,5 @@ requirements: []
 rubygems_version: 3.3.22
 signing_key:
 specification_version: 4
-summary: Generates a branch name based on a JIRA card/ticket number.
+summary: Generates a branch name based on a JIRA ticket/ticket number.
 test_files: []

data/lib/branch/name/nameable.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Branch
-  module Name
-    module Nameable
-      def normalize_branch_name(branch_name)
-        branch_name.strip!
-        branch_name = branch_name.split.join options[:separator]
-        branch_name.downcase! if options[:downcase]
-        branch_name.tr!('_', '-') if options[:separator] == '-'
-        branch_name.tr!('-', '_') if options[:separator] == '_'
-        branch_name.squeeze!('-') if options[:separator] == '-'
-        branch_name.squeeze!('_') if options[:separator] == '_'
-        branch_name
-      end
-    end
-  end
-end