Merge branch 'master' into relationships-nested-under

.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

.github/workflows/codeql.yml

@@ -0,0 +1,100 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "master" ]
+    paths-ignore:
+      - '**/*.md'
+      - 'http-basic-example.rb'
+      - 'example.rb'
+  pull_request:
+    branches: [ "master" ]
+    paths-ignore:
+      - '**/*.md'
+      - 'http-basic-example.rb'
+      - 'example.rb'
+  schedule:
+    - cron: '0 13 * * *'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: ruby
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - if: matrix.build-mode == 'manual'
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

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
 
@@ -99,7 +176,7 @@ defaults to HTTP Basic Auth.
 
 Jira supports cookie based authentication whereby user credentials are passed
 to JIRA via a JIRA REST API call.  This call returns a session cookie which must
-then be sent to all following JIRA REST API calls. 
+then be sent to all following JIRA REST API calls.
 
 To enable cookie based authentication, set `:auth_type` to `:cookie`,
 set `:use_cookies` to `true` and set `:username` and `:password` accordingly.
@@ -114,7 +191,7 @@ options = {
   :context_path       => '',
   :auth_type          => :cookie,  # Set cookie based authentication
   :use_cookies        => true,     # Send cookies with each request
-  :additional_cookies => ['AUTH=vV7uzixt0SScJKg7'] # Optional cookies to send 
+  :additional_cookies => ['AUTH=vV7uzixt0SScJKg7'] # Optional cookies to send
                                                    # with each request
 }
 
@@ -134,15 +211,40 @@ cookie to add to the request.
 
 Some authentication schemes that require additional cookies ignore the username
 and password sent in the JIRA REST API call.  For those use cases, `:username`
-and `:password` may be omitted from `options`. 
+and `:password` may be omitted from `options`.
+
+## Configuring JIRA to use Personal Access Tokens Auth
+If your JIRA system is configured to support Personal Access Token authorization, minor modifications are needed in how credentials are communicated to the server.  Specifically, the paremeters `:username` and `:password` are not needed.  Also, the parameter `:default_headers` is needed to contain the api_token, which can be obtained following the official documentation from [Atlassian](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).  Please note that the Personal Access Token can only be used as it is. If it is encoded (with base64 or any other encoding method) then the token will not work correctly and authentication will fail.
+
+```ruby
+require 'jira-ruby'
+
+# NOTE: the token should not be encoded
+api_token = API_TOKEN_OBTAINED_FROM_JIRA_UI
+
+options = {
+  :site               => 'http://mydomain.atlassian.net:443/',
+  :context_path       => '',
+  :username           => '<the email you sign-in to Jira>',
+  :password           => api_token,
+  :auth_type          => :basic
+}
 
+client = JIRA::Client.new(options)
+
+project = client.Project.find('SAMPLEPROJECT')
+
+project.issues.each do |issue|
+  puts "#{issue.id} - #{issue.summary}"
+end
+```
 ## Using the API Gem in a command line application
 
 Using HTTP Basic Authentication, configure and connect a client to your instance
 of JIRA.
 
 Note: If your Jira install is hosted on [atlassian.net](atlassian.net), it will have no context
-path by default. If you're having issues connecting, try setting context_path 
+path by default. If you're having issues connecting, try setting context_path
 to an empty string in the options hash.
 
 ```ruby