jira-auto-tool 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef155479c2de20dfb3e3832c19a641451e04f80223f72d549f00b9deef55bfb1
-  data.tar.gz: fd35c88ae871e535a8d5a2423a2a93725593f9124a290656b37221b229071905
+  metadata.gz: 17df99358f86abaa36bf5e36882881e34df34de901441daf121e98b86fbd4ea2
+  data.tar.gz: 9fb2d8b44488861db052fdabab616260ca0b276dfd1f595a39ccff8822a83b0b
 SHA512:
-  metadata.gz: b5913dded0750570c80fe1be755edf588a1f136f0ba417ff1168ae6093d1fa58406252f18280a4158c46971532445d20a00c0b4bbf82cd800176192f776664ff
-  data.tar.gz: '09aeea8783e1c9ff219b202e1b6ad031870e802b4f4b6bdfaeb33f3adeed47f8ca93056f79127a50edda131b115e4f232fc19be0e794e30ecafd28e954c6ca0c'
+  metadata.gz: 7d65dab75a5828d2d2ecc2c533aca864abb0a4f541f662ab4740fcda352805e80482bd6c8aefefc5bd13290a1b2365072732f5813b6365e9928d373ca7f300a7
+  data.tar.gz: a62f5ad58f3cb57756c5c1e9589665553eb802cfa1e8af60629cf27aea3451a0129e4b7a1b808ce28b2db98eb2d5d3da1d44ac8fadb81b49dcabbe176777299b

data/README.md

@@ -35,10 +35,19 @@ in such a cloud sandbox. Though, if the sandbox belongs to the target context
 
 ## Setup
 
+1. Create an example configuration file
+   ```bash
+   jira-auto-tool --env-setup
+   ```
+2. Adjust the file to your context. 
+
+**WARNING** - It is highly recommended that the JIRA_API_TOKEN value is set as an environment variable 
+and **NOT** in the generated file.
+
 While we strive to use convention over configuration as a principle, the following environment variables have to be set
 in order to use this tool:
 
-Required environment variables:
+Some explanations:
 
 - `JIRA_USERNAME` - Your Jira account username (e.g., "user@company.com").
 - `JIRA_API_TOKEN` - Your Jira API authentication token.
@@ -63,19 +72,20 @@ See [sprint filtering](./features/sprint_filtering.feature).
 
 ## Usage
 
-* Leverage the [specification by examples](./features)
 * Use the tool integrated help: 
   ```bash
   jira-auto-tool --help
   ```
-* Usually the long option names have a short version equivalent to reduce typing.
+* Leverage the [specification by examples](./features) for a detailled understand of the features.
+* Note that usually the long option names have a short version equivalent to reduce typing.
 
 Below are a few examples.
 
 ### Add Sprints
 
-The following is going to create sprints `sprint_prefix_25.4.3` until `sprint_prefix_25.4.6` 
-for the teams respective sprint prefixes. 
+The following is going to [add sprints](./features/create_sprints_using_existing_ones_as_reference.feature) 
+`sprint_prefix_25.4.3` until `sprint_prefix_25.4.6` 
+to the teams respective sprint prefixes. 
 ```bash
 jira-auto-tool --sprint-add=25.4.3,4
 ```

data/bin/jira-auto-tool

@@ -20,6 +20,7 @@ require "jira/auto/tool"
 require "jira/auto/tool/board_controller/options"
 require "jira/auto/tool/common_options"
 require "jira/auto/tool/config/options"
+require "jira/auto/tool/environment_loader/options"
 require "jira/auto/tool/jira_http_options"
 require "jira/auto/tool/performer/options"
 require "jira/auto/tool/project/options"
@@ -36,6 +37,7 @@ option_parser = OptionParser.new do |parser|
   Jira::Auto::Tool::JiraHttpOptions.add(tool, parser)
   Jira::Auto::Tool::BoardController::Options.add(tool, parser)
   Jira::Auto::Tool::Config::Options.add(tool, parser)
+  Jira::Auto::Tool::EnvironmentLoader::Options.add(tool, parser)
   Jira::Auto::Tool::Project::Options.add(tool, parser)
   Jira::Auto::Tool::Performer::Options.add(tool, parser)
   Jira::Auto::Tool::SprintController::Options.add(tool, parser)

data/config/examples/jira-auto-tool.env.yaml.erb

@@ -0,0 +1,28 @@
+---
+<%
+  project_key = "PROJ"
+  sprint_field_name = "Sprint"
+  jira_username = "cbroult@yahoo.com"
+%>
+##JIRA_API_TOKEN: WARNING - it is recommended to set the value directly as an environment variable
+ART_SPRINT_REGEX:
+DISABLE_COVERAGE: true
+EXPECTED_START_DATE_FIELD_NAME: Expected Start
+IMPLEMENTATION_TEAM_FIELD_NAME: "Implementation Team"
+JAT_RATE_INTERVAL_IN_SECONDS:
+JAT_RATE_LIMIT_IN_SECONDS:
+JAT_TICKETS_FOR_TEAM_SPRINT_TICKET_DISPATCHER_JQL: "project = <%= project_key %> AND <%= sprint_field_name %> IS EMPTY"
+JIRA_BOARD_NAME: "<%= project_key %> - Your board name"
+JIRA_BOARD_NAME_REGEX: "<%= project_key %>|ART 16|unconventional board name"
+JIRA_CONTEXT_PATH: /jira
+JIRA_HTTP_DEBUG:
+JIRA_PROJECT_KEY: <%= project_key %>
+JIRA_SITE_URL: http://cbroult.atlassian.net:443/
+JIRA_SPRINT_FIELD_NAME: "<%= sprint_field_name %>"
+JIRA_USERNAME: <%= jira_username %>
+
+<%
+  message = "TODO: set the values specific to your context and remove this part of the file"
+  log.error { message  }
+  raise message
+%>

data/documentation/JiraToolClassDiagram.uml

@@ -0,0 +1,44 @@
+classDiagram
+    class Tool {
+    }
+    
+    class BoardController {
+    }
+    
+    class SprintController {
+    }
+    
+    class BoardOptions {
+        +add(tool, parser)$
+    }
+    
+    class SprintOptions {
+        +add(tool, parser)$
+        +add_sprint_adding_options(parser, tool)$
+        +add_sprint_listing_options(parser, tool)$
+        +add_sprint_prefix_listing_options(parser, tool)$
+    }
+    
+    class UntilDate {
+    }
+    
+    class Cache {
+    }
+
+    Tool --> BoardController : has
+    Tool --> SprintController : has
+    BoardController --> BoardOptions : uses
+    SprintController --> SprintOptions : uses
+    BoardController --> Cache : uses
+    SprintOptions --> UntilDate : uses
+
+    %% Namespace structure
+    namespace Jira {
+        namespace Auto {
+            Tool
+            namespace Tool {
+                BoardController
+                SprintController
+            }
+        }
+    }

data/documentation/class_diagram.md

@@ -0,0 +1,48 @@
+# Overall Class Diagram Structure
+
+```mermaid
+classDiagram
+    class Tool {
+    }
+    
+    class BoardController {
+    }
+    
+    class SprintController {
+    }
+    
+    class BoardOptions {
+        +add(tool, parser)$
+    }
+    
+    class SprintOptions {
+        +add(tool, parser)$
+        +add_sprint_adding_options(parser, tool)$
+        +add_sprint_listing_options(parser, tool)$
+        +add_sprint_prefix_listing_options(parser, tool)$
+    }
+    
+    class UntilDate {
+    }
+    
+    class Cache {
+    }
+
+    Tool --> BoardController : has
+    Tool --> SprintController : has
+    BoardController --> BoardOptions : uses
+    SprintController --> SprintOptions : uses
+    BoardController --> Cache : uses
+    SprintOptions --> UntilDate : uses
+
+    %% Namespace structure
+    namespace Jira {
+        namespace Auto {
+            Tool
+            namespace Tool {
+                BoardController
+                SprintController
+            }
+        }
+    }
+```

data/documentation/principle.md

@@ -0,0 +1,6 @@
+# Principles
+
+## Configuration Over Configuration
+
+## 
+

data/features/configure_environment.feature

@@ -0,0 +1,166 @@
+@wip
+Feature: Environment Configuration Management
+  In order to avoid setting environment variables manually
+  As a user of jira-auto-tool
+  I want to be able to configure the tool using a configuration file
+
+  Scenario: Creating the environment configuration file
+    Given a file named "~/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb" does not exist
+    When I successfully run `jira-auto-tool --env-create-file`
+    Then the output should match:
+      """
+      \s+INFO\s+Jira::Auto::Tool::EnvironmentLoader\s+:\s+Created\s+file\s.+/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb
+      _______________________________________________
+      TODO: Adjust the configuration to your context!
+      """
+    And a file named "~/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb" should contain exactly:
+      """
+      ---
+      <%
+        project_key = "PROJ"
+        sprint_field_name = "Sprint"
+        jira_username = "cbroult@yahoo.com"
+      %>
+      ##JIRA_API_TOKEN: WARNING - it is recommended to set the value directly as an environment variable
+      ART_SPRINT_REGEX:
+      DISABLE_COVERAGE: true
+      EXPECTED_START_DATE_FIELD_NAME: Expected Start
+      IMPLEMENTATION_TEAM_FIELD_NAME: "Implementation Team"
+      JAT_RATE_INTERVAL_IN_SECONDS:
+      JAT_RATE_LIMIT_IN_SECONDS:
+      JAT_TICKETS_FOR_TEAM_SPRINT_TICKET_DISPATCHER_JQL: "project = <%= project_key %> AND <%= sprint_field_name %> IS EMPTY"
+      JIRA_BOARD_NAME: "<%= project_key %> - Your board name"
+      JIRA_BOARD_NAME_REGEX: "<%= project_key %>|ART 16|unconventional board name"
+      JIRA_CONTEXT_PATH: /jira
+      JIRA_HTTP_DEBUG:
+      JIRA_PROJECT_KEY: <%= project_key %>
+      JIRA_SITE_URL: http://cbroult.atlassian.net:443/
+      JIRA_SPRINT_FIELD_NAME: "<%= sprint_field_name %>"
+      JIRA_USERNAME: <%= jira_username %>
+
+      <%
+        message = "TODO: set the values specific to your context and remove this part of the file"
+        log.error { message  }
+        raise message
+      %>
+      """
+
+
+  Scenario: Not overriding an existing environment configuration file
+    Given a file named "~/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb" with:
+      """
+      ---
+      JIRA_TOKEN: 'a dummy token'
+      """
+    When I run `jira-auto-tool --env-create-file`
+    Then it should fail matching:
+      """
+      ERROR\s+Jira::Auto::Tool::EnvironmentLoader\s+:\s+Not\s+overriding\s+existing\s+.+/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb
+      ______________________________________________
+      Please remove first before running this again!
+      """
+
+  Scenario: Tool successfully loads the config
+    Given a file named "jira-auto-tool.env.yaml.erb" with:
+      """
+      ---
+      <%
+        jira_username = "user@jira.instance.com"
+        project_key = 'PROJ'
+        sprint_field_name = 'Sprint'
+      %>
+
+      ART_SPRINT_REGEX:
+      EXPECTED_START_DATE_FIELD_NAME: Expected Start
+      IMPLEMENTATION_TEAM_FIELD_NAME: "Implementation Team"
+      JAT_RATE_INTERVAL_IN_SECONDS:
+      JAT_RATE_LIMIT_IN_SECONDS:
+      JAT_TICKETS_FOR_TEAM_SPRINT_TICKET_DISPATCHER_JQL: "project = <%= project_key %> AND <%= sprint_field_name %> IS EMPTY"
+      JIRA_API_TOKEN: "current API TOKEN"
+      JIRA_BOARD_NAME: "Team Board"
+      JIRA_BOARD_NAME_REGEX: "ART 16|unconventional board name"
+      JIRA_CONTEXT_PATH: /jira
+      JIRA_HTTP_DEBUG:
+      JIRA_PROJECT_KEY: <%= project_key %>
+      JIRA_SITE_URL: "<%= 'https://example.atlassian.net' %>"
+      JIRA_SPRINT_FIELD_NAME: "<%= sprint_field_name %>"
+      JIRA_USERNAME: "<%= jira_username %>"
+      """
+    When I successfully run `jira-auto-tool --env-list`
+    Then the output should contain exactly:
+      """
+      Using configuration from ./jira-auto-tool.env.yaml.erb
++---------------------------------------------------+------------------------------------+
+| Name                                              | Value                              |
++---------------------------------------------------+------------------------------------+
+| ART_SPRINT_REGEX                                  |                                    |
+| EXPECTED_START_DATE_FIELD_NAME                    | Expected Start                     |
+| IMPLEMENTATION_TEAM_FIELD_NAME                    | Implementation Team                |
+| JAT_RATE_INTERVAL_IN_SECONDS                      |                                    |
+| JAT_RATE_LIMIT_IN_SECONDS                         |                                    |
+| JAT_TICKETS_FOR_TEAM_SPRINT_TICKET_DISPATCHER_JQL | project = PROJ AND Sprint IS EMPTY |
+| JIRA_API_TOKEN                                    | current API TOKEN                  |
+| JIRA_BOARD_NAME                                   | Team Board                         |
+| JIRA_BOARD_NAME_REGEX                             | ART 16|unconventional board name   |
+| JIRA_CONTEXT_PATH                                 | /jira                              |
+| JIRA_HTTP_DEBUG                                   |                                    |
+| JIRA_PROJECT_KEY                                  | PROJ                               |
+| JIRA_SITE_URL                                     | https://example.atlassian.net      |
+| JIRA_SPRINT_FIELD_NAME                            | Sprint                             |
+| JIRA_USERNAME                                     | user@jira.instance.com             |
++---------------------------------------------------+------------------------------------+
+      """
+
+  Scenario: Tool looks first for configuration in the current directory
+    Given a file named "./jira-auto-tool.env.yaml.erb" with:
+      """
+      ---
+      JIRA_USERNAME: "current@company.com"
+      JIRA_API_TOKEN: "current-token"
+      JIRA_SITE_URL: "https://current.atlassian.net"
+      """
+    And a file named "~/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb" with:
+      """
+      ---
+      JIRA_USERNAME: "home@company.com"
+      JIRA_API_TOKEN: "home-token"
+      JIRA_SITE_URL: "https://home.atlassian.net"
+      """
+    When I successfully run `jira-auto-tool --env-list`
+    Then the output should contain:
+      """
+      Using configuration from ./jira-auto-tool.env.yaml.erb
+      """
+
+  Scenario: Tool looks for home directory config folder when no config file in the current directory
+    Given a file named "./jira-auto-tool.env.yaml.erb" does not exist
+    And a file named "~/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb" with:
+      """
+      JIRA_USERNAME: "home@company.com"
+      JIRA_API_TOKEN: "home-token"
+      JIRA_SITE_URL: "https://home.atlassian.net"
+      """
+    When I successfully run `jira-auto-tool --env-list`
+    Then the output should match:
+      """
+      Using configuration from .+/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb
+      """
+
+  Scenario: Tool uses the existing environment values if no config file found
+    Given the following files should not exist:
+      | ./jira-auto-tool.env.yaml.erb                        |
+      | ~/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb |
+    And the following environment variables are set:
+      | name           | value       |
+      | JIRA_API_TOKEN | token-value |
+    When I successfully run `jira-auto-tool --env-list`
+    Then the output should match:
+      """
+      Only using the environment variables since neither of the following files exist:
+      ./jira-auto-tool.env.yaml.erb
+      .+/.config/jira-auto-tool/jira-auto-tool.env.yaml.erb
+      """
+    And the output should match:
+      """
+      JIRA_API_TOKEN\s+|token-value\s+
+      """

data/lib/jira/auto/tool/config/options.rb

@@ -5,11 +5,12 @@ module Jira
     class Tool
       class Config
         class Options
-          def self.add(_tool, parser)
+          def self.add(_tool, _parser)
             # parser.section_header "Config"
-            #
+
             # parser.on("--config-list") do
-            #   # TODO: tool.config.list
+            # Config.list
+            # TODO: tool.config.list
             # end
           end
         end

data/lib/jira/auto/tool/config.rb

@@ -32,15 +32,19 @@ module Jira
         end
 
         def path
-          File.join(dir, "jira-auto-tool.config.yml")
+          File.join(dir, "#{tool_name}.config.yml")
         end
 
         def dir
-          config_dir = File.join(Dir.home, ".config/jira-auto-tool")
+          config_dir = File.join(Dir.home, ".config/#{tool_name}")
           FileUtils.makedirs(config_dir)
           config_dir
         end
 
+        def tool_name
+          "jira-auto-tool"
+        end
+
         private
 
         def sanitize_key(key)

data/lib/jira/auto/tool/environment_loader/options.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jira
+  module Auto
+    class Tool
+      class EnvironmentLoader
+        module Options
+          def self.add(tool, parser)
+            parser.section_header "Environment"
+
+            parser.on("--env-list", "List the environment_loader variables used by the tool") do
+              tool.environment.list
+            end
+
+            parser.on("--env-create-file", "Create the environment configuration file") { tool.environment.create_file }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jira/auto/tool/environment_loader.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Jira
+  module Auto
+    class Tool
+      class EnvironmentLoader
+        attr_reader :tool
+
+        def initialize(tool, auto_setup: true)
+          @tool = tool
+
+          setup if auto_setup
+        end
+
+        def create_file
+          if File.exist?(file_path)
+            log.error do
+              <<~EOERRORMESSAGE
+                Not overriding existing #{file_path}
+                ______________________________________________
+                Please remove first before running this again!
+              EOERRORMESSAGE
+            end
+
+            Kernel.exit 1
+          else
+            FileUtils.cp(example_file_path, file_path)
+
+            log.info do
+              <<~EOMESSAGE
+                Created file #{file_path}
+                _______________________________________________
+                TODO: Adjust the configuration to your context!
+              EOMESSAGE
+            end
+          end
+        end
+
+        def list
+          $stdout.puts <<~EOLIST
+            #{configuration_source_string}
+            #{table}
+          EOLIST
+        end
+
+        def tool_environment
+          Environment.constants.sort.to_h do |constant|
+            constant_as_string = constant.to_s
+
+            [constant_as_string, ENV.fetch(constant_as_string, nil)]
+          end
+        end
+
+        def file_path
+          File.exist?(current_dir_file_path) ? current_dir_file_path : config_dir_file_path
+        end
+
+        def example_file_path
+          File.join(tool.home_dir, "config/examples", file_basename)
+        end
+
+        CURRENT_DIR = "."
+
+        private
+
+        def setup
+          config_values.each { |key, value| ENV[key] = value }
+        end
+
+        def configuration_source_string
+          if File.exist?(file_path)
+            "Using configuration from #{file_path}"
+          else
+            <<~EOENV_ONLY
+              Only using the environment variables since neither of the following files exist:
+              #{current_dir_file_path}
+              #{config_dir_file_path}
+            EOENV_ONLY
+          end
+        end
+
+        def config_values
+          @config_values ||= YAML.safe_load(config_file_content) || {}
+        end
+
+        def config_file_content
+          @config_file_content ||= File.exist?(file_path) ? ERB.new(File.read(file_path)).result(binding) : ""
+        end
+
+        def table
+          Terminal::Table.new do |t|
+            t.headings = %w[Name Value]
+            t.rows = tool_environment.to_a
+          end
+        end
+
+        def config
+          tool.config
+        end
+
+        def config_dir_file_path
+          File.join(config.dir, file_basename)
+        end
+
+        def current_dir_file_path
+          File.join(CURRENT_DIR, file_basename)
+        end
+
+        def file_basename
+          "#{config.tool_name}.env.yaml.erb"
+        end
+      end
+    end
+  end
+end

data/lib/jira/auto/tool/helpers/environment_based_value.rb

@@ -55,10 +55,10 @@ module Jira
             constant_name = method_name.to_s.upcase
             class_eval <<-EOCONSTANT, __FILE__, __LINE__ + 1
               # This module and constant will be interpolated as follows:
-              # module Environment
+              # class Environment
               #   CONSTANT_NAME = "CONSTANT_NAME"
               # end
-              module Environment
+              class Environment
                  #{constant_name} = #{constant_name.inspect}
               end
             EOCONSTANT
@@ -70,7 +70,7 @@ module Jira
             environment_variable_name = caller_method_name.upcase
 
             value = ENV.fetch(environment_variable_name) do |name|
-              raise KeyError, "Missing #{name} environment variable!"
+              raise KeyError, "Missing #{name} environment_loader variable!"
             end
 
             log.debug { "fetch_corresponding_environment_variable(#{environment_variable_name}) - #{value.inspect}" }

data/lib/jira/auto/tool/version.rb

@@ -3,7 +3,7 @@
 module Jira
   module Auto
     class Tool
-      VERSION = "1.0.0"
+      VERSION = "1.1.0"
     end
   end
 end

data/lib/jira/auto/tool.rb

@@ -8,6 +8,7 @@ require "jira-ruby"
 
 require_relative "tool/config"
 require_relative "tool/board_controller"
+require_relative "tool/environment_loader"
 require_relative "tool/helpers/environment_based_value"
 require_relative "tool/project"
 require_relative "tool/rate_limited_jira_client"
@@ -23,15 +24,26 @@ require_relative "tool/version"
 
 module Jira
   module Auto
+    # rubocop:disable Metrics/ClassLength
     class Tool
       extend Helpers::EnvironmentBasedValue
 
       class Error < StandardError; end
 
+      attr_reader :environment
+
+      def initialize
+        @environment = EnvironmentLoader.new(self)
+      end
+
       def config
         @config ||= Config.new(self)
       end
 
+      def home_dir
+        File.expand_path(File.join("..", "..", ".."), __dir__)
+      end
+
       def board_name
         jira_board_name
       end
@@ -212,5 +224,7 @@ module Jira
           .create_sprint(self, board.id, attributes)
       end
     end
+
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/spec/jira/auto/tool/common_options_spec.rb

@@ -12,7 +12,10 @@ module Jira
             let(:tool) { Tool.new }
             let(:parser) { OptionParser.new }
 
-            before { described_class.add(tool, parser) }
+            before do
+              allow(EnvironmentLoader).to receive_messages(new: instance_double(EnvironmentLoader))
+              described_class.add(tool, parser)
+            end
 
             context "when using --help" do
               it do

data/spec/jira/auto/tool/environment_loader_spec.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "rspec"
+
+module Jira
+  module Auto
+    class Tool
+      class EnvironmentLoader
+        RSpec.describe EnvironmentLoader do
+          let(:environment_loader) { described_class.new(tool, auto_setup: auto_setup) }
+          let(:auto_setup) { false }
+          let(:tool) { instance_double(Tool, config: config) }
+          let(:config) { instance_double(Config, dir: "config_dir", tool_name: "jira-auto-tool") }
+
+          # rubocop:disable RSpec/AnyInstance
+          describe "#initialize" do
+            context "when auto_setup is true" do
+              let(:auto_setup) { true }
+
+              it do
+                expect_any_instance_of(described_class).to receive(:setup)
+
+                environment_loader
+              end
+            end
+
+            context "when auto_setup is false" do
+              let(:auto_setup) { false }
+
+              it do
+                expect_any_instance_of(described_class).not_to receive(:setup)
+
+                environment_loader
+              end
+            end
+          end
+          # rubocop:enable RSpec/AnyInstance
+
+          describe "#file_path" do
+            before do
+              allow(File).to receive(:exist?).with("./jira-auto-tool.env.yaml.erb")
+                                             .and_return(current_directory_file_exists)
+            end
+
+            context "when file exists in current directory" do
+              let(:current_directory_file_exists) { true }
+
+              it { expect(environment_loader.file_path).to eq("./jira-auto-tool.env.yaml.erb") }
+            end
+
+            context "when file does not exist in current directory" do
+              let(:current_directory_file_exists) { false }
+
+              it { expect(environment_loader.file_path).to eq("config_dir/jira-auto-tool.env.yaml.erb") }
+            end
+          end
+
+          describe "#tool_environment" do
+            let(:environment_keys) { %i[JIRA_HOST JIRA_USER JIRA_PASSWORD] }
+
+            before do
+              allow(Environment).to receive(:constants).and_return(environment_keys)
+
+              environment_keys.each do |environment_key|
+                allow(ENV).to receive(:fetch).with(environment_key.to_s, nil).and_return("#{environment_key} value")
+              end
+            end
+
+            it do
+              expect(environment_loader.tool_environment).to eq(
+                "JIRA_HOST" => "JIRA_HOST value",
+                "JIRA_USER" => "JIRA_USER value",
+                "JIRA_PASSWORD" => "JIRA_PASSWORD value"
+              )
+            end
+          end
+
+          describe "#create_file" do
+            let(:logger) { instance_double(Logger) }
+
+            before do
+              allow(environment_loader)
+                .to receive_messages(file_path: "file_path", example_file_path: "example_file_path", log: logger)
+
+              allow(File).to receive(:exist?).with("file_path").and_return(file_path_exists)
+            end
+
+            context "when file does not exist" do
+              let(:file_path_exists) { false }
+
+              it "copies the example config file" do
+                expect(FileUtils).to receive(:cp).with("example_file_path", "file_path")
+
+                expect(logger).to receive(:info) do |&block|
+                  expect(block.call).to eq(<<~EOCREATIONMESSAGE)
+                    Created file file_path
+                    _______________________________________________
+                    TODO: Adjust the configuration to your context!
+                  EOCREATIONMESSAGE
+                end
+
+                environment_loader.create_file
+              end
+            end
+
+            context "when file already exists" do
+              let(:file_path_exists) { true }
+
+              it "does not copy the example config file if it already exists" do
+                expect(logger).to receive(:error) do |&block|
+                  expect(block.call).to eq(<<~EOEXPECTED_ERROR_MESSAGE)
+                    Not overriding existing file_path
+                    ______________________________________________
+                    Please remove first before running this again!
+                  EOEXPECTED_ERROR_MESSAGE
+                end
+
+                expect(Kernel).to receive(:exit).with(1)
+
+                environment_loader.create_file
+              end
+            end
+          end
+
+          describe "#example_file_path" do
+            before { allow(tool).to receive_messages(home_dir: "<JIRA_AUTO_TOOL_HOME_DIR>") }
+
+            it "returns the path to the example config file" do
+              expect(environment_loader.example_file_path)
+                .to eq("<JIRA_AUTO_TOOL_HOME_DIR>/config/examples/jira-auto-tool.env.yaml.erb")
+            end
+          end
+
+          describe "#setup" do
+            it "sets up the value according to the configuration file content" do
+              allow(environment_loader).to receive_messages(file_path: "file_path")
+              allow(environment_loader).to receive_messages(config_file_content: "file_content")
+
+              allow(YAML)
+                .to receive(:safe_load).with("file_content")
+                                       .and_return({ "a_key" => "a_value", "another_key" => "another_value" })
+
+              expect(ENV).to receive(:[]=).with("a_key", "a_value")
+              expect(ENV).to receive(:[]=).with("another_key", "another_value")
+
+              environment_loader.send(:setup)
+            end
+          end
+
+          describe "#config_file_content" do
+            let(:file_path) { "file_path" }
+            let(:file_content) do
+              <<-YAML_ERB
+                ---
+                a_key: <%= 4*4 %>
+                another_key: another_value
+              YAML_ERB
+            end
+
+            let(:erb_result) do
+              <<-YAML
+                ---
+                a_key: 16
+                another_key: another_value
+              YAML
+            end
+
+            before do
+              allow(environment_loader).to receive_messages(file_path: file_path)
+              allow(File).to receive(:exist?).with(file_path).and_return(true)
+              allow(File).to receive(:read).with(file_path).and_return(file_content)
+            end
+
+            it { expect(environment_loader.send(:config_file_content)).to eq(erb_result) }
+          end
+        end
+      end
+    end
+  end
+end

data/spec/jira/auto/tool_spec.rb

@@ -9,6 +9,8 @@ module Jira
       RSpec.describe Tool do
         let(:tool) { described_class.new }
 
+        before { allow(EnvironmentLoader).to receive_messages(new: instance_double(EnvironmentLoader)) }
+
         it "has a version number" do
           expect(Jira::Auto::Tool::VERSION).not_to be_nil
         end
@@ -40,6 +42,14 @@ module Jira
           end
         end
 
+        describe "#environment_loader" do
+          let(:environment_loader) { instance_double(EnvironmentLoader) }
+
+          before { allow(EnvironmentLoader).to receive_messages(new: environment_loader) }
+
+          it { expect(tool.environment).to eq(environment_loader) }
+        end
+
         # rubocop:disable RSpec/StubbedMock
         describe "#create_sprint" do
           it "creates a future sprint and transitions it to the desired state" do
@@ -103,6 +113,10 @@ module Jira
           it { expect(tool.sprint_controller).to be_a(SprintController) }
         end
 
+        describe "#home_dir" do
+          it { expect(tool.home_dir).to eq(File.expand_path("../../../", __dir__)) }
+        end
+
         describe "#project" do
           let(:jira_client) { instance_double(RateLimitedJiraClient, Project: project_query) }
           let(:jira_project) { instance_double(JIRA::Resource::Project) }
@@ -117,7 +131,7 @@ module Jira
         end
 
         # TODO: move that to environment_based_value_spec
-        RSpec.shared_examples "an overridable environment based value" do |method_name|
+        RSpec.shared_examples "an overridable environment_loader based value" do |method_name|
           let(:env_var_name) { method_name.to_s.upcase }
           let(:method_name?) { :"#{method_name}_defined?" }
           let(:config) { Config.new(object_with_overridable_value) }
@@ -127,7 +141,7 @@ module Jira
             allow(config).to receive_messages(value_store: {})
           end
 
-          context "when the environment variable is set" do
+          context "when the environment_loader variable is set" do
             let(:expected_value) { "#{env_var_name} env_value" }
 
             before do
@@ -142,7 +156,7 @@ module Jira
                 .to eq(expected_value)
             end
 
-            it "fetches its value from the environment" do
+            it "fetches its value from the environment_loader" do
               expect(object_with_overridable_value.send(method_name)).to eq(expected_value)
             end
 
@@ -159,11 +173,11 @@ module Jira
             end
           end
 
-          context "when the environment variable is not set" do
+          context "when the environment_loader variable is not set" do
             before do
               allow(ENV).to receive(:fetch)
                 .with(env_var_name)
-                .and_raise(KeyError.new("Missing #{env_var_name} environment variable!)"))
+                .and_raise(KeyError.new("Missing #{env_var_name} environment_loader variable!)"))
 
               allow(ENV).to receive(:key?).with(env_var_name).and_return(false)
             end
@@ -175,9 +189,9 @@ module Jira
                 .to eq("DEFAULT_VALUE")
             end
 
-            it "raises an error if the environment variable is not found" do
+            it "raises an error if the environment_loader variable is not found" do
               expect { object_with_overridable_value.send(method_name) }
-                .to raise_error(KeyError, /Missing #{env_var_name} environment variable!/)
+                .to raise_error(KeyError, /Missing #{env_var_name} environment_loader variable!/)
             end
           end
 
@@ -218,10 +232,10 @@ module Jira
           jira_site_url jira_username
           jira_sprint_field_name
         ].each do |method_name|
-          describe "environment based values" do
+          describe "environment_loader based values" do
             let(:object_with_overridable_value) { tool }
 
-            it_behaves_like "an overridable environment based value", method_name
+            it_behaves_like "an overridable environment_loader based value", method_name
           end
         end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jira-auto-tool
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Christophe Broult
@@ -213,10 +213,15 @@ files:
 - bin/jira-auto-tool.bat
 - bin/setup
 - bin/setup-dev-win.bat
+- config/examples/jira-auto-tool.env.yaml.erb
 - cucumber.yml
+- documentation/JiraToolClassDiagram.uml
+- documentation/class_diagram.md
+- documentation/principle.md
 - features/align_sprint_time_in_dates.feature
 - features/assign_tickets_to_team_sprints.feature
 - features/cache_boards.feature
+- features/configure_environment.feature
 - features/control_http_request_rate_limit.feature
 - features/create_sprints_using_existing_ones_as_reference.feature
 - features/list_boards.feature
@@ -246,6 +251,8 @@ files:
 - lib/jira/auto/tool/common_options.rb
 - lib/jira/auto/tool/config.rb
 - lib/jira/auto/tool/config/options.rb
+- lib/jira/auto/tool/environment_loader.rb
+- lib/jira/auto/tool/environment_loader/options.rb
 - lib/jira/auto/tool/fetch_custom_field_options.rb
 - lib/jira/auto/tool/field.rb
 - lib/jira/auto/tool/field_controller.rb
@@ -299,6 +306,7 @@ files:
 - spec/jira/auto/tool/board_spec.rb
 - spec/jira/auto/tool/common_options_spec.rb
 - spec/jira/auto/tool/config_spec.rb
+- spec/jira/auto/tool/environment_loader_spec.rb
 - spec/jira/auto/tool/field_controller_spec.rb
 - spec/jira/auto/tool/field_option_spec.rb
 - spec/jira/auto/tool/field_spec.rb