Merge branch 'master' into max_retries

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: Bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+A runnable code example to reproduce the issue.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: Feature
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context about the feature request here.

.github/workflows/CI.yml

@@ -0,0 +1,28 @@
+name: Ruby
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    name: CI-tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - '3.3'
+          - '3.2'
+          - '3.1'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: |
+          bundle exec rake jira:generate_public_cert
+          bundle exec rake spec

Gemfile

@@ -1,4 +1,4 @@
-source 'http://rubygems.org'
+source 'https://rubygems.org'
 
 group :development do
   gem 'guard'

README.md

@@ -1,37 +1,114 @@
 # JIRA API Gem
 
 [![Code Climate](https://codeclimate.com/github/sumoheavy/jira-ruby.svg)](https://codeclimate.com/github/sumoheavy/jira-ruby)
-[![Build Status](https://travis-ci.org/sumoheavy/jira-ruby.svg?branch=master)](https://travis-ci.org/sumoheavy/jira-ruby)
+[![Build Status](https://github.com/sumoheavy/jira-ruby/actions/workflows/CI.yml/badge.svg)](https://github.com/sumoheavy/jira-ruby/actions/workflows/CI.yml)
 
 This gem provides access to the Atlassian JIRA REST API.
 
-## Slack
+## Example usage
 
-Join our Slack channel! You can find us [here](https://jira-ruby-slackin.herokuapp.com/)
+# Jira Ruby API - Sample Usage
 
-## Example usage
+This sample usage demonstrates how you can interact with JIRA's API using the [jira-ruby gem](https://github.com/sumoheavy/jira-ruby).
 
-```ruby
-require 'rubygems'
-require 'jira-ruby'
+### Dependencies
+
+Before running, install the `jira-ruby` gem:
 
+```shell
+gem install jira-ruby
+```
+
+### Sample Usage
+Connect to JIRA
+Firstly, establish a connection with your JIRA instance by providing a few configuration parameters:
+There are other ways to connect to JIRA listed below |  [Personal Access Token](#configuring-jira-to-use-personal-access-tokens-auth)
+- private_key_file: The path to your RSA private key file.
+- consumer_key: Your consumer key.
+- site: The URL of your JIRA instance.
+
+```ruby
 options = {
-  :username     => 'username',
-  :password     => 'pass1234',
-  :site         => 'http://mydomain.atlassian.net:443/',
-  :context_path => '',
-  :auth_type    => :basic
+  :private_key_file => "rsakey.pem",
+  :context_path     => '',
+  :consumer_key     => 'your_consumer_key',
+  :site             => 'your_jira_instance_url'
 }
 
 client = JIRA::Client.new(options)
+```
 
-project = client.Project.find('SAMPLEPROJECT')
+### Retrieve and Display Projects
 
-project.issues.each do |issue|
-  puts "#{issue.id} - #{issue.summary}"
+After establishing the connection, you can fetch all projects and display their key and name:
+```ruby
+projects = client.Project.all
+
+projects.each do |project|
+  puts "Project -> key: #{project.key}, name: #{project.name}"
 end
 ```
 
+### Handling Fields by Name
+The jira-ruby gem allows you to refer to fields by their custom names rather than identifiers. Make sure to map fields before using them:
+
+```ruby
+client.Field.map_fields
+
+old_way = issue.customfield_12345
+
+# Note: The methods mapped here adopt a unique style combining PascalCase and snake_case conventions.
+new_way = issue.Special_Field
+```
+
+### JQL Queries
+To find issues based on specific criteria, you can use JIRA Query Language (JQL):
+
+```ruby
+client.Issue.jql(a_normal_jql_search, fields:[:description, :summary, :Special_field, :created])
+```
+
+### Several actions can be performed on the Issue object such as create, update, transition, delete, etc:
+### Creating an Issue
+```ruby
+issue = client.Issue.build
+labels = ['label1', 'label2']
+issue.save({
+  "fields" => {
+    "summary" => "blarg from in example.rb",
+    "project" => {"key" => "SAMPLEPROJECT"},
+    "issuetype" => {"id" => "3"},
+    "labels" => labels,
+    "priority" => {"id" => "1"}
+  }
+})
+```
+
+### Updating/Transitioning an Issue
+```ruby
+issue = client.Issue.find("10002")
+issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA!"}})
+
+issue_transition = issue.transitions.build
+issue_transition.save!('transition' => {'id' => transition_id})
+```
+
+### Deleting an Issue
+```ruby
+issue = client.Issue.find('SAMPLEPROJECT-2')
+issue.delete
+```
+
+### Other Capabilities
+Apart from the operations listed above, this API wrapper supports several other capabilities like:
+	•	Searching for a user
+	•	Retrieving an issue's watchers
+	•	Changing the assignee of an issue
+	•	Adding attachments and comments to issues
+	•	Managing issue links and much more.
+
+Not all examples are shown in this README; refer to the complete script example for a full overview of the capabilities supported by this API wrapper.
+
 ## Links to JIRA REST API documentation
 
 * [Overview](https://developer.atlassian.com/display/JIRADEV/JIRA+REST+APIs)
@@ -87,7 +164,7 @@ key.
 > After you have entered all the information click OK and ensure OAuth authentication is
 > enabled.
 
-For 2 legged oauth in server mode only, not in cloud based JIRA, make sure to `Allow 2-Legged OAuth`
+For two legged oauth in server mode only, not in cloud based JIRA, make sure to `Allow 2-Legged OAuth`
 
 ## Configuring JIRA to use HTTP Basic Auth
 

jira-ruby.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
   s.licenses    = ['MIT']
   s.metadata    = { 'source_code_uri' => 'https://github.com/sumoheavy/jira-ruby' }
 
-  s.required_ruby_version = '>= 1.9.3'
+  s.required_ruby_version = '>= 3.1.0'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
@@ -22,14 +22,14 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'activesupport'
   s.add_runtime_dependency 'atlassian-jwt'
   s.add_runtime_dependency 'multipart-post'
-  s.add_runtime_dependency 'oauth', '~> 0.5', '>= 0.5.0'
+  s.add_runtime_dependency 'oauth', '~> 1.0'
 
   # Development Dependencies
-  s.add_development_dependency 'guard', '~> 2.13', '>= 2.13.0'
-  s.add_development_dependency 'guard-rspec', '~> 4.6', '>= 4.6.5'
-  s.add_development_dependency 'pry', '~> 0.10', '>= 0.10.3'
+  s.add_development_dependency 'guard', '~> 2.18', '>= 2.18.1'
+  s.add_development_dependency 'guard-rspec', '~> 4.7', '>= 4.7.3'
+  s.add_development_dependency 'pry', '~> 0.14', '>= 0.14.3'
   s.add_development_dependency 'railties'
-  s.add_development_dependency 'rake', '~> 10.3', '>= 10.3.2'
-  s.add_development_dependency 'rspec', '~> 3.0', '>= 3.0.0'
-  s.add_development_dependency 'webmock', '~> 1.18', '>= 1.18.0'
+  s.add_development_dependency 'rake', '~> 13.2', '>= 13.2.1'
+  s.add_development_dependency 'rspec', '~> 3.0', '>= 3.13'
+  s.add_development_dependency 'webmock', '~> 3.23', '>= 3.23.0'
 end

lib/jira-ruby.rb

@@ -18,6 +18,7 @@
 require 'jira/resource/issuetype'
 require 'jira/resource/version'
 require 'jira/resource/status'
+require 'jira/resource/status_category'
 require 'jira/resource/transition'
 require 'jira/resource/project'
 require 'jira/resource/priority'
@@ -32,11 +33,11 @@
 require 'jira/resource/remotelink'
 require 'jira/resource/sprint'
 require 'jira/resource/sprint_report'
+require 'jira/resource/resolution'
 require 'jira/resource/issue'
 require 'jira/resource/filter'
 require 'jira/resource/field'
 require 'jira/resource/rapidview'
-require 'jira/resource/resolution'
 require 'jira/resource/serverinfo'
 require 'jira/resource/createmeta'
 require 'jira/resource/webhook'

lib/jira/base.rb

@@ -141,7 +141,7 @@ def self.collection_path(client, prefix = '/')
     #   JIRA::Resource::Comment.singular_path('456','/issue/123/')
     #     # => /jira/rest/api/2/issue/123/comment/456
     def self.singular_path(client, key, prefix = '/')
-      collection_path(client, prefix) + '/' + key
+      collection_path(client, prefix) + '/' + key.to_s
     end
 
     # Returns the attribute name of the attribute used for find.

lib/jira/client.rb

@@ -184,6 +184,10 @@ def Status # :nodoc:
       JIRA::Resource::StatusFactory.new(self)
     end
 
+    def StatusCategory # :nodoc:
+      JIRA::Resource::StatusCategoryFactory.new(self)
+    end
+
     def Resolution # :nodoc:
       JIRA::Resource::ResolutionFactory.new(self)
     end
@@ -293,7 +297,7 @@ def post(path, body = '', headers = {})
 
     def post_multipart(path, file, headers = {})
       puts "post multipart: #{path} - [#{file}]" if @http_debug
-      @request_client.request_multipart(path, file, headers)
+      @request_client.request_multipart(path, file, merge_default_headers(headers))
     end
 
     def put(path, body = '', headers = {})

lib/jira/http_client.rb

@@ -45,12 +45,12 @@ def basic_auth_http_conn
     end
 
     def http_conn(uri)
-      if @options[:proxy_address]
-        http_class = Net::HTTP::Proxy(@options[:proxy_address], @options[:proxy_port] || 80, @options[:proxy_username], @options[:proxy_password])
-      else
-        http_class = Net::HTTP
-      end
-      http_conn = http_class.new(uri.host, uri.port)
+      http_conn =
+        if @options[:proxy_address]
+          Net::HTTP.new(uri.host, uri.port, @options[:proxy_address], @options[:proxy_port] || 80, @options[:proxy_username], @options[:proxy_password])
+        else
+          Net::HTTP.new(uri.host, uri.port)
+        end
       http_conn.use_ssl = @options[:use_ssl]
       if @options[:use_client_cert]
         http_conn.cert = @options[:ssl_client_cert]

lib/jira/http_error.rb

@@ -1,4 +1,6 @@
 require 'forwardable'
+require 'active_support/core_ext/object'
+
 module JIRA
   class HTTPError < StandardError
     extend Forwardable