story_branch 1.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4196567f738d9eefe7e9b689bba4a082f3604d41c7e4b198f10295e3f867a0ba
-  data.tar.gz: 4bd0f419c7fce7703c1b5df98d906137bfd6b3c53e400273c59caf8bea923d26
+  metadata.gz: 470bb59ffdc939bd91f9700a00f467ca2b68535d7a30740b95792cb6c43b37e3
+  data.tar.gz: 49ca86d91a3f963f4096b84a3192ebc9a8da547a6dc0bb44fc465c4ca5eb149b
 SHA512:
-  metadata.gz: 60993c9099b5112018ea6949ad47901bc27349473296ba96590bed89b499d96eea9ad185623d66d16ba28216b71d8efcbbd91131e89cb51e17da370037416eca
-  data.tar.gz: 0a5154411fdb3c53b5efc0e444af8383b9a197e241bb0ffbe0322c38ccf56d92ee5501e1f3b25026aa1b181b10c66736f9fce90fb25a1a3df1d0530defea7729
+  metadata.gz: 9627d3631e828b32bb5d064f0580d4b940c23dd6c19d809583be4d32e52298646978355316c009870c8d9fb05b8611137137374dfbb644c6554bb0d176f21c6a
+  data.tar.gz: cc087771f69a847b3822181c8156aec52515993aba41a4fb7c3af01f33961c8a32826eae0d242d931595cebf9c00c6a8f4301a8498e87bbeeb218bfcf69ef715

data/.circleci/config.yml

@@ -1,15 +1,14 @@
-version: 2
-
-defaults: &defaults
-  docker:
-    - image: circleci/ruby:2.6.5-node
-  working_directory: ~/repo
+version: 2.1
 
 workflows:
   version: 2
   test-and-publish:
     jobs:
       - test:
+          matrix:
+            parameters:
+              ruby_version: ["ruby:2.6-buster", "ruby:2.7-buster", "ruby:3.0-buster"]
+
           filters:
             tags:
               # this enables circleci to trigger on tags
@@ -26,7 +25,12 @@ workflows:
 
 jobs:
   test:
-    <<: *defaults
+    parameters:
+      ruby_version:
+        type: string
+    docker:
+      - image: circleci/<< parameters.ruby_version >>
+    working_directory: ~/repo
 
     steps:
       - checkout
@@ -38,22 +42,12 @@ jobs:
             chmod +x ./cc-test-reporter
       - run: ./cc-test-reporter before-build
 
-      - restore_cache:
-          keys:
-          - v2-dependencies-{{ checksum "Gemfile.lock" }}
-          - v2-dependencies-
-
       - run:
           name: install dependencies
           command: |
             gem install bundler
             bundle install --jobs=4 --retry=3 --path vendor/bundle
 
-      - save_cache:
-          paths:
-            - ./vendor/bundle
-          key: v2-dependencies-{{ checksum "Gemfile.lock" }}
-
       - run:
           name: run tests
           command: |
@@ -81,26 +75,19 @@ jobs:
             ./cc-test-reporter after-build -t simplecov --exit-code $?
 
   publish:
-    <<: *defaults
+    docker:
+      - image: circleci/ruby:3.0-buster
+    working_directory: ~/repo
+
     steps:
       - checkout
 
-      - restore_cache:
-          keys:
-          - v2-dependencies-{{ checksum "Gemfile.lock" }}
-          - v2-dependencies-
-
       - run:
           name: install dependencies
           command: |
             gem install bundler
             bundle install --jobs=4 --retry=3 --path vendor/bundle
 
-      - save_cache:
-          paths:
-            - ./vendor/bundle
-          key: v2-dependencies-{{ checksum "Gemfile.lock" }}
-
       - run:
           name: Setup Rubygems
           command: bash .circleci/setup-rubygems.sh

data/.github/workflows/rubocop.yml

@@ -8,12 +8,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v1
-    - name: Set up Ruby 2.6
-      uses: actions/setup-ruby@v1
-      with:
-        ruby-version: 2.6.x
+    - uses: actions/checkout@v3
+    - name: Set up Ruby 2.7
+      uses: ruby/setup-ruby@v1
     - name: Rubocop Linter
-      uses: andrewmcodes/rubocop-linter-action@v0.1.2
+      uses: andrewmcodes/rubocop-linter-action@v3.3.0
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.gitignore

@@ -4,3 +4,4 @@ story_branch-*.gem
 .byebug_history
 coverage
 tools/release*.*
+Gemfile.lock

data/.story_branch.yml

@@ -1,5 +1,5 @@
 ---
-finish_tag: 'Resolves'
-tracker: 'github'
+finish_tag: Resolves
+tracker: github
 project_id:
 - story-branch/story_branch

data/Changelog.md

@@ -1,3 +1,16 @@
+# 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
+
+- Add configuration support to prepend branch name with a user prefix (#122)
+
 # 0.3.3
 Tue Jun 26 15:18:37 2018 +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'
 
@@ -14,6 +15,7 @@ module StoryBranch
     # and then add the project id specified by the user.
     class Configure < StoryBranch::Command
       def initialize(_options)
+        super()
         @new_config = ConfigManager.new
       end
 
@@ -72,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/commands/create.rb

@@ -8,6 +8,7 @@ module StoryBranch
     # started stories in the tracker
     class Create < StoryBranch::Command
       def initialize(options)
+        super()
         @options = options
       end
 

data/lib/story_branch/commands/finish.rb

@@ -7,6 +7,7 @@ module StoryBranch
     # Command to finish a story
     class Finish < StoryBranch::Command
       def initialize(options)
+        super()
         @options = options
       end
 

data/lib/story_branch/commands/open_issue.rb

@@ -7,6 +7,7 @@ module StoryBranch
     # OpenIssue command is used to open the associated ticket in the browser
     class OpenIssue < StoryBranch::Command
       def initialize(options)
+        super()
         @options = options
       end
 

data/lib/story_branch/commands/start.rb

@@ -7,6 +7,7 @@ module StoryBranch
     # Command to start an estimated story
     class Start < StoryBranch::Command
       def initialize(options)
+        super()
         @options = options
       end
 

data/lib/story_branch/commands/unstart.rb

@@ -7,6 +7,7 @@ module StoryBranch
     # Command to unstart a previously started story
     class Unstart < StoryBranch::Command
       def initialize(options)
+        super()
         @options = options
       end
 

data/lib/story_branch/config_manager.rb

@@ -34,6 +34,10 @@ module StoryBranch
       @issue_placement ||= @config.fetch(:issue_placement, default: 'End')
     end
 
+    def branch_username
+      @branch_username ||= @config.fetch(project_key, :branch_username)
+    end
+
     def finish_tag
       @finish_tag ||= @config.fetch(project_key,
                                     :finish_tag, default: 'Finishes')

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