story_branch 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7a8e6bc148fecde83a3f76f088507313660e6ab1cd4fb059d61285b380c583d
-  data.tar.gz: c5a1c714d28331dd096ff89858af114055adf528ac63a33326b5ee6893c0cb4c
+  metadata.gz: 470bb59ffdc939bd91f9700a00f467ca2b68535d7a30740b95792cb6c43b37e3
+  data.tar.gz: 49ca86d91a3f963f4096b84a3192ebc9a8da547a6dc0bb44fc465c4ca5eb149b
 SHA512:
-  metadata.gz: f4f7c388a01ad1a9c164c0e21997422fe020416927afd164bfc68042fa958fb95f102909ffda013c26ab38f8d963e0de3d9894fa063413cd3469b3cdbccf76d5
-  data.tar.gz: 164713630f809f65b4c703bd90cfba6007586837b903a869553c9f95d16ff3169f9b56821036674aca4bd6cac7e1617acf3e28c2425f53088aba60cbb238f7e1
+  metadata.gz: 9627d3631e828b32bb5d064f0580d4b940c23dd6c19d809583be4d32e52298646978355316c009870c8d9fb05b8611137137374dfbb644c6554bb0d176f21c6a
+  data.tar.gz: cc087771f69a847b3822181c8156aec52515993aba41a4fb7c3af01f33961c8a32826eae0d242d931595cebf9c00c6a8f4301a8498e87bbeeb218bfcf69ef715

data/Changelog.md

@@ -1,3 +1,11 @@
+# 2.2.0
+
+Wed Aug 11 07:37:00 2022 +0800
+
+- Add support for linear.app (#127)
+  - Adds dependency on story branch's graphql client
+- Update README to match closer to current gem behavior
+
 # 2.1.0
 Wed Jul 20 18:30:00 2022 +0800
 

data/README.md

@@ -2,6 +2,29 @@
 [![CircleCI](https://circleci.com/gh/story-branch/story_branch/tree/master.svg?style=svg)](https://circleci.com/gh/story-branch/story_branch/tree/master)
 [![Maintainability](https://api.codeclimate.com/v1/badges/7dbd75908417656853d7/maintainability)](https://codeclimate.com/github/story-branch/story_branch/maintainability)
 
+# Table of Contents
+
+* [Installing](#installing)
+* [Usage](#usage)
+* [Commands available](#commands-available)
+* [Commentary](#commentary)
+    * [Configuration](#configuration)
+        * [Configuring PivotalTracker](#configuring-pivotaltracker)
+        * [Configuring Github](#configuring-github)
+        * [Configuring JIRA](#configuring-jira)
+        * [Configuring LinearApp](#configuring-linearapp)
+        * [Available settings](#available-settings)
+            * [Issue placement](#issue-placement)
+            * [Branch username](#branch-username)
+            * [Finish tag](#finish-tag)
+    * [Creating a new branch following the naming convention](#creating-a-new-branch-following-the-naming-convention)
+    * [PivotalTracker specific commands](#pivotaltracker-specific-commands)
+* [Migrating](#migrating)
+    * [Old configuration](#old-configuration)
+    * [Old commands](#old-commands)
+* [Contributing](#contributing)
+
+
 # Story Branch
 
 Story branch is a CLI application that interacts with Pivotal Tracker, Github and Jira
@@ -46,25 +69,97 @@ Commands:
   story_branch version         # story_branch gem version
 ```
 
-## Settings
+## Commentary
+
+`story_branch configure`: Step by step configuration of a new tracker for your project
+
+### Configuration
+
+The configuration is split into two different files: a `.story_branch.yml` in the root folder
+of the project where you're configuring the tool and a `.story_branch.yml` in user's home directory.
+
+For the management of the home directory, story_branch relies on [XDG](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
+specification, so if configured, it'll be installed under `~/.config` or whatever your machine
+specifies.
+
+The idea behind the two files is that the one in the root of the project should be committed to your
+repository and defines basic tracker configuration settings to be shared across the contributors
+to your repository. These configuration settings include the tracker type, project id in the tracker,
+where you want the ticket number to be placed amongst others.
+
+The file under your config directory is meant to be stored only locally as it will contain the api
+keys needed for story branch to access your tracker. The story_branch file under your config directory
+should not be published anywhere.
 
-Story branch has a command available that will help you creating the configurations
-for the projects, but essentially you'll be asked for the pivotal tracker project id and your api key.
+#### Configuring PivotalTracker
+
+When running the command `story_branch configure` you'll be asked 3 things:
+1. tracker - You should select Pivotal Tracker
+2. project id - This can be fetched from the PivotalTracker url. E.g in the url `https://www.pivotaltracker.com/n/projects/651417`, the project id would be `651417`
+3. api key - this is your personal api key. You can get that from [your profile page](https://www.pivotaltracker.com/profile)
+
+#### Configuring Github
+
+When running the command `story_branch configure` you'll be asked 3 things:
+1. tracker - You should select Github
+2. project id - This is the github repository name in the format `<owner>/<repo_name>`. E.g. `story-branch/story_branch`.
+3. api key - this is your personal api token. You can create one under your [developer profile tokens page](https://github.com/settings/tokens)
+
+#### Configuring JIRA
+
+The configuration for JIRA is slightly more complex as the endpoint changes according
+to your project setup. You will need an API token, which you can create a new one in your [JIRA id management page](https://id.atlassian.com/manage/api-tokens)
+1. tracker - You should select JIRA
+2. JIRA's subdomain - you should type the JIRA's subdomain that you use to access in your browser. E.g I'd type perxtechnologies to access to <https://perxtechnologies.atlassian.net>
+3. JIRA's project key - this should match which project you want to fetch the issues from. E.g. PW is the key for my Project Whistler, so I'd type PW
+4. API key that you should have gotten in the first description step
+5. username used for login in the JIRA usually. If you use google email authentication, the username should be your email
+
+#### Configuring LinearApp
+
+When running the command `story_branch configure` you'll be asked 3 things:
+1. tracker - You should select LinearApp
+2. project id - This should be your team's id.
+3. api key - this is your personal api token. You can create one under your [account API settings](https://linear.app/settings/api)
+
+#### Available settings
+
+##### Issue placement
+
+On your local config you can add a line with `issue_placement: <Beginning|End>`.
+Based on this configuration, when running `story_branch create`, the ticket id will be
+used as prefix or suffix on the branch name.
+
+E.g.
+`issue_placement: Beginning`
 
-### Configuring the project id
+`story_branch create` will create a branch in the format: `<issue_number>-<issue_title>`
 
-The project id you can get it easily from the url when viewing the project.
-This value will be stored in the local configuration file that will be committed
-to the working repository
+While
 
-### Configuring the api key
+`issue_placement: End`
 
-The api key you can get it from your account settings.
-This value will be stored in your global configuration file that typically is
-not shared with your co-workers in the repository. This way, each user will
-be properly identified in the tracker
+`story_branch create` will create a branch in the format: `<issue_title>-<issue_number>`
 
-### Configuring the finish tag
+##### Branch username
+
+In some cases your workflow requires you to have an identifier prefixing the branch name.
+You can configure that by setting the configuration `branch_username` under your project's
+name in the global `story_branch.yml` file (`defaults to: ~/.config/.story_branch.yml`)
+
+E.g.
+
+```
+story-branch/story_branch:
+  api_key: my_fantastic_api_key
+  branch_username: rui
+```
+
+Doing so, when running `story_branch create`, it will create a branch in the format: `rui/<issue_number>-<issue_title>`
+
+Naturally, the issue number will be placed based on the issue placement setting
+
+##### Finish tag
 
 On your local config you can add a line with `finish_tag: <Some random word>`.
 This tag will be used in the commit message when running `story_branch finish`.
@@ -75,28 +170,11 @@ E.g.
 `story_branch finish` will make a commit with the message
 `[Resolves #12313] story title`
 
+### Creating a new branch following the naming convention
 
-### .story_branch files
-
-When configuring story branch, it will create two .story_branch.yml files: one in
-your home folder (`~/`) and one in your project's root (`./`).
-The one in your home folder will be used to store the different project's configurations
-such as which api key to use. This is done so you don't need to commit your
-api key to the repository but still be able to use different keys in case you
-have different accounts.
-
-The one in your project root will keep a reference to the project configuration.
-For now, this reference is the project id. This file can be safely committed to
-the repository and shared amongst your co-workers.
-
-## Commentary
-
-`story_branch create`: Creates a git branch with automatic reference to a
-Pivotal Tracker Story. It will get started stories from your active
-project. You can enter text and press TAB to search for a story
-name, or TAB to show the full list. It will then suggest an editable
-branch name. When the branch is created the `story_id` will
-be appended to it.
+`story_branch create`: Creates a git branch with automatic reference to a tracker ticket.
+The tickets/stories that will be fetched will depend on the project type. Once you choose the
+ticket to work on, a new branch will be created based on the ticket title and id.
 
 e.g. `my-story-name-1234567`
 
@@ -107,6 +185,8 @@ e.g: `[Finishes #1234567] My story name`
 You must stage all changes (or stash them) first. Note the commit will not
 be pushed. Note: You'll be able to bail out of the commit.
 
+### PivotalTracker specific commands
+
 `story_branch start`: Start a story in Pivotal Tracker from the terminal.
 It'll get all un-started stories in your current project. You can
 enter text and press TAB to search for a story name, or TAB to show
@@ -117,31 +197,6 @@ It'll get all started stories in your current project. You can
 enter text and press TAB to search for a story name, or TAB to show
 the full list.
 
-## Configuring PivotalTracker
-
-When running the command `story_branch configure` you'll be asked 3 things:
-1. tracker - You should select Pivotal Tracker
-2. project id - This can be fetched from the PivotalTracker url. E.g in the url `https://www.pivotaltracker.com/n/projects/651417`, the project id would be `651417`
-3. api key - this is your personal api key. You can get that from [your profile page](https://www.pivotaltracker.com/profile)
-
-## Configuring Github
-
-When running the command `story_branch configure` you'll be asked 3 things:
-1. project id - This is the github repository name in the format `<owner>/<repo_name>`. E.g. `story-branch/story_branch`.
-2. tracker - You should select Github
-3. api key - this is your personal api token. You can create one under your
-[developer profile tokens page](https://github.com/settings/tokens)
-
-## Configuring JIRA
-
-The configuration for JIRA is slightly more complex as the endpoint changes according
-to your project setup. You will need an API token, which you can create a new one in your [JIRA id management page](https://id.atlassian.com/manage/api-tokens)
-1. tracker - You should select JIRA
-2. JIRA's subdomain - you should type the JIRA's subdomain that you use to access in your browser. E.g I'd type perxtechnologies to access to https://perxtechnologies.atlassian.net
-3. JIRA's project key - this should match which project you want to fetch the issues from. E.g. PW is the key for my Project Whistler, so I'd type PW
-4. API key that you should have gotten in the first description step
-5. username used for login in the JIRA usually. If you use google email authentication, the username should be your email
-
 ## Migrating
 
 ### Old configuration

data/lib/story_branch/commands/configure.rb

@@ -2,6 +2,7 @@
 
 require_relative '../config_manager'
 require_relative '../command'
+require_relative '../constants'
 require 'tty-config'
 require 'tty-prompt'
 
@@ -73,12 +74,7 @@ module StoryBranch
       def tracker
         return @tracker if @tracker
 
-        trackers = {
-          'Pivotal Tracker' => 'pivotal-tracker',
-          'Github' => 'github',
-          'JIRA' => 'jira'
-        }
-        @tracker = prompt.select('Which tracker are you using?', trackers)
+        @tracker = prompt.select('Which tracker are you using?', StoryBranch::AVAILABLE_TRACKERS)
       end
     end
   end

data/lib/story_branch/constants.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module StoryBranch
+  AVAILABLE_TRACKERS = {
+    'Pivotal Tracker' => 'pivotal-tracker',
+    'Github' => 'github',
+    'JIRA' => 'jira',
+    'LinearApp' => 'linearapp'
+  }.freeze
+
+  TRACKERS_CLASSES = {
+    'pivotal-tracker' => 'StoryBranch::Pivotal::Tracker',
+    'github' => 'StoryBranch::Github::Tracker',
+    'jira' => 'StoryBranch::Jira::Tracker',
+    'linearapp' => 'StoryBranch::LinearApp::Tracker'
+  }.freeze
+end

data/lib/story_branch/issue_base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module StoryBranch
+  # Base class to represent an issue/ticket
+  class IssueBase
+    attr_reader :title, :id, :html_url
+
+    def initialize(tracker_issue, project = nil)
+      @project = project
+      @story = tracker_issue
+    end
+
+    def to_s
+      "#{@id} - #{@title}"
+    end
+
+    def dashed_title
+      StoryBranch::StringUtils.normalised_branch_name @title
+    end
+  end
+end

data/lib/story_branch/linear_app/issue.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../issue_base'
+
+module StoryBranch
+  module LinearApp
+    # LinearApp Issue representation
+    class Issue < StoryBranch::IssueBase
+      # NOTE: project here represents the team_id only
+      def initialize(tracker_issue, project)
+        super
+        @title = tracker_issue['title']
+        @id = "#{@project}-#{tracker_issue['number']}"
+        @html_url = tracker_issue['url']
+      end
+    end
+  end
+end

data/lib/story_branch/linear_app/team.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'issue'
+
+module StoryBranch
+  module LinearApp
+    # LinearApp groups tickets in teams, so this is the team representation in
+    # story branch. It's equivalent to a project
+    class Team
+      def initialize(team_id, client)
+        @team_id = team_id
+        @client = client
+      end
+
+      def stories(_options = {})
+        response = @client.get(graphql_query: graphql_query)
+        stories_json = response.data['viewer']['assignedIssues']['nodes']
+        stories_json.map { |story| Issue.new(story, @team_id) }
+      rescue StoryBranch::Graphql::Error => e
+        raise "Error while querying for tickets:\n#{e.message}"
+      end
+
+      private
+
+      def graphql_query # rubocop:disable Metrics/MethodLength
+        %(
+          query Issue {
+            viewer {
+              assignedIssues (filter: { team: { name: { eq: "#{@team_id}"} } }) {
+                nodes {
+                  id
+                  title
+                  description
+                  number
+                  url
+                }
+              }
+            }
+          }
+        )
+      end
+    end
+  end
+end

data/lib/story_branch/linear_app/tracker.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'story_branch/graphql'
+require_relative '../tracker_base'
+require_relative 'team'
+
+module StoryBranch
+  module LinearApp
+    # Linear App API wrapper for story branch tracker
+    class Tracker < StoryBranch::TrackerBase
+      API_URL = 'https://api.linear.app/'
+
+      def initialize(project_id:, api_key:, **)
+        super
+
+        # NOTE: project should be the representation of linear app team
+        @team_id = project_id
+        @api_key = api_key
+      end
+
+      def valid?
+        !@api_key.nil? && !@team_id.nil?
+      end
+
+      # TODO: This should probably be renamed to something more meaningful
+      # in the sense that it should be workable stories/issues
+      # which depend on the tracker's workflow. PivotalTracker they need to
+      # be started and estimated, while for Github they just need to be open
+      def stories
+        project.stories
+      end
+
+      def get_story_by_id(story_id)
+        project.stories(id: story_id).first
+      end
+
+      def client
+        @client ||= StoryBranch::Graphql::Client.new(api_url: API_URL, api_key: @api_key)
+      end
+
+      private
+
+      def configure_api
+        client
+      end
+
+      def project
+        return @project if @project
+        raise 'team must be set' unless @team_id
+
+        @project = Team.new(@team_id, client)
+      end
+    end
+  end
+end

data/lib/story_branch/main.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
-require_relative './pivotal/tracker'
-require_relative './github/tracker'
-require_relative './jira/tracker'
 require_relative './git_utils'
 require_relative './git_wrapper'
 require_relative './config_manager'
 require_relative './url_opener'
+require_relative 'tracker_initializer'
+
 require 'tty-prompt'
 
 module StoryBranch
@@ -20,7 +19,7 @@ module StoryBranch
     def initialize
       @config = ConfigManager.new
       abort(@config.errors.join("\n")) unless @config.valid?
-      @tracker = initialize_tracker
+      @tracker = StoryBranch::TrackerInitializer.initialize_tracker(config: @config)
       abort('Invalid tracker configuration setting.') unless @tracker.valid?
     end
 
@@ -209,20 +208,6 @@ module StoryBranch
     def current_branch
       @current_branch ||= GitWrapper.current_branch
     end
-
-    def initialize_tracker
-      # TODO: Ideally this would be mapped out somewhere so we don't need to
-      # evaluate anything from the config here
-      tracker_type = @config.tracker_type
-      case tracker_type
-      when 'github'
-        StoryBranch::Github::Tracker.new(**@config.tracker_params)
-      when 'pivotal-tracker'
-        StoryBranch::Pivotal::Tracker.new(**@config.tracker_params)
-      when 'jira'
-        StoryBranch::Jira::Tracker.new(**@config.tracker_params)
-      end
-    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/story_branch/tracker_initializer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative './constants'
+require_relative './pivotal/tracker'
+require_relative './github/tracker'
+require_relative './jira/tracker'
+require_relative './linear_app/tracker'
+
+module StoryBranch
+  # helper class to find out which tracker should be initialized based on the
+  # configuration values
+  class TrackerInitializer
+    def self.initialize_tracker(config:)
+      tracker_class = find_tracker_class(config.tracker_type)
+      raise 'Invalid tracker configuration' unless tracker_class
+
+      tracker_class.new(**config.tracker_params)
+    end
+
+    def self.find_tracker_class(tracker_type)
+      tracker_str = StoryBranch::TRACKERS_CLASSES[tracker_type]
+      return nil unless tracker_str
+
+      Kernel.const_get(tracker_str)
+    end
+  end
+end

data/lib/story_branch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StoryBranch
-  VERSION = '2.1.0'
+  VERSION = '2.2.0'
 end

data/story_branch.gemspec

@@ -55,7 +55,9 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'blanket_wrapper', '~> 3.0', '> 3.0'
   spec.add_runtime_dependency 'damerau-levenshtein', '~> 1.3', '> 1.3'
+  spec.add_runtime_dependency 'httparty', '>0'
   spec.add_runtime_dependency 'jira-ruby', '> 1.7', '< 3'
+  spec.add_runtime_dependency 'story_branch-graphql', '~> 0.0.1'
   spec.add_runtime_dependency 'thor', '> 0.20', '< 2'
   spec.add_runtime_dependency 'tty-command', '~> 0.8', '> 0.8'
   spec.add_runtime_dependency 'tty-config', '~> 0.2', '> 0.2'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: story_branch
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Rui Baltazar
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-07-20 00:00:00.000000000 Z
+date: 2022-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: blanket_wrapper
@@ -54,6 +54,20 @@ dependencies:
     - - ">"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: jira-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -74,6 +88,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
+- !ruby/object:Gem::Dependency
+  name: story_branch-graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.1
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -441,6 +469,7 @@ files:
 - lib/story_branch/commands/start.rb
 - lib/story_branch/commands/unstart.rb
 - lib/story_branch/config_manager.rb
+- lib/story_branch/constants.rb
 - lib/story_branch/git_utils.rb
 - lib/story_branch/git_wrapper.rb
 - lib/story_branch/github/issue.rb
@@ -448,9 +477,13 @@ files:
 - lib/story_branch/github/milestone.rb
 - lib/story_branch/github/project.rb
 - lib/story_branch/github/tracker.rb
+- lib/story_branch/issue_base.rb
 - lib/story_branch/jira/issue.rb
 - lib/story_branch/jira/project.rb
 - lib/story_branch/jira/tracker.rb
+- lib/story_branch/linear_app/issue.rb
+- lib/story_branch/linear_app/team.rb
+- lib/story_branch/linear_app/tracker.rb
 - lib/story_branch/main.rb
 - lib/story_branch/pivotal/project.rb
 - lib/story_branch/pivotal/story.rb
@@ -466,6 +499,7 @@ files:
 - lib/story_branch/templates/start/.gitkeep
 - lib/story_branch/templates/unstart/.gitkeep
 - lib/story_branch/tracker_base.rb
+- lib/story_branch/tracker_initializer.rb
 - lib/story_branch/url_opener.rb
 - lib/story_branch/version.rb
 - story_branch.gemspec