octokitted 0.0.9 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6eb37191994ca5fbce98292fa7d110d1b8ba0cef9adbfdcee64ff9a4c86783c5
-  data.tar.gz: dddf0023f475c442215e2c73c0112782cbef093c4725d321e72d3bcff9edffaf
+  metadata.gz: 9e2273f42d15b208e1c3044e0357230b800cfc9e9868c0921df2c77b054ea9b9
+  data.tar.gz: c4ab08a959a98b1bce866644b7b8dcbbb7b3e40ac09fb6b5cc80a65d10803c12
 SHA512:
-  metadata.gz: 256b887a612783254b34ccabb3f4e8c348df57656f1562507453802bf37252214157164f79d45032ef8231e05ccc46b8b25f4a82e8f9850b17eff5ff5e7249c8
-  data.tar.gz: dc678d7dd0658e9ea8e0d8983b99f17784836140140b31e303b5718b7c39d465706db56061a9d26e79d48ea609b83599c6b2b61eed5330309f07a389ad0ce55d
+  metadata.gz: 4687eb29d75b078b0e5f2b15ef4391a1a518aac3a64fb1a04c36c421b6e435967929df8287f71e159a80193a3404a38a0df49435d4ab49f4020c5b9acdeea87a
+  data.tar.gz: 24b3c9d44929a10a6ea7c0aea947b40f84c4694827a1f5d0901c919e0497c68195da963bf7e45b3d76996d499d55feed545905b91f45faeac0bef262ae11bcd0

data/README.md

@@ -11,3 +11,169 @@ A self-hydrating version of Octokit for usage in CI systems - like GitHub Action
 > "we were all kitted out in life jackets", "our octokit client was kitted out for CI usage"
 
 ![octokitted](./docs/assets/dalle.png)
+
+## Installation 💎
+
+You can download this Gem from either [RubyGems](https://rubygems.org/gems/octokitted) or [GitHub Packages](https://github.com/GrantBirki/octokitted/pkgs/rubygems/octokitted)
+
+RubyGems (Recommended):
+
+```bash
+gem install octokitted
+```
+
+> RubyGems [link](https://rubygems.org/gems/octokitted)
+
+Via a Gemfile:
+
+```ruby
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "octokit", "~> 7.1" # a dependency of octokitted
+gem "octokitted", "~> X.X.X" # Replace X.X.X with the latest version
+```
+
+## Usage 💻
+
+This section goes over general usage of this Gem
+
+For full usage documentation of available methods, please see the [docs](./docs/usage.md)
+
+### Configuration
+
+The following table goes into detail about the configuration options that can be passed into the `Octokitted.new()` constructor:
+
+> It should be noted that when calling `Octokitted.new()` in the proper GitHub Action's context, no configuration is required to be passed into `.new()` because this Gem will fully self-hydrate itself. The `Required` field is only in the table below for reference if you are not running this Gem in GitHub Actions.
+
+| Option | Environment Variable | Description | Required |
+| ------ | -------------------- | ----------- | -------- |
+| `login` | - | The GitHub handle associated with the provided `token`. Defaults to the owner of the token | no |
+| `org` | `GITHUB_REPOSITORY` | The GitHub organization or user that owns a given repository. This value self-hydrates from the `GITHUB_REPOSITORY` env var when run in GitHub Actions | no, can be set after construction |
+| `repo` | `GITHUB_REPOSITORY` | The GitHub repository name. This value self-hydrates from the `GITHUB_REPOSITORY` env var when run in GitHub Actions | no, can be set after construction |
+| `issue_number` | `GITHUB_EVENT_PATH` | The GitHub issue number. This value self-hydrates from the `GITHUB_EVENT_PATH` env var when run in GitHub Actions. The event json object is read from disk on the Action's runner which contains issue number information | no, can be set after construction |
+| `token` | `GITHUB_TOKEN` or `OCTOKIT_ACCESS_TOKEN` | The GitHub token to use for authentication. This value self-hydrates from the `GITHUB_TOKEN` env var when run in GitHub Actions | yes, required for construction |
+| `logger` | - | The logger to use for logging. You can pass in your own logger or use the one this Gem auto-creates by default | no |
+
+It should be noted that you can configure the log level that is used through the `LOG_LEVEL` environment variable. The default log level is `INFO`.
+
+### GitHub Actions
+
+If you are running in the context of a **pull request** or an **issue** in GitHub Actions, you can simply create a new instance of `Octokitted` and it will automatically hydrate itself:
+
+```ruby
+# frozen_string_literal: true
+
+require "octokitted"
+
+# Setup a new instance of Octokitted and self-hydrate
+gh = Octokitted.new()
+
+puts "#{gh.org} #{gh.repo} #{gh.org_and_repo}"
+# => GrantBirki octokitted GrantBirki/octokitted
+
+puts gh.issue_number
+# => 123
+
+# add a comment to the issue in the context we are running in
+gh.issue.add_comment(comment: "Hello from Octokitted!")
+
+# add a label to the issue
+gh.issue.add_labels(labels: ["test"])
+
+# remove the label from the issue
+gh.issue.remove_labels(labels: ["test"])
+
+# close the issue
+gh.issue.close
+
+# swap your context to a different issue
+gh.issue_number = 456
+puts gh.issue_number
+# => 456
+
+```
+
+### Outside of GitHub Actions
+
+If you want to use Octokitted outside of GitHub Actions, you can pass some of the required information to the constructor:
+
+```ruby
+# frozen_string_literal: true
+
+require "octokitted"
+
+# Setup a new instance of Octokitted with explicit values
+gh = Octokitted.new(
+    login: "GrantBirki", # The user associated with the GITHUB_TOKEN
+    org: "GrantBirki", # The organization associated with the repo
+    repo: "octokitted", # The repo name
+    token: ENV.fetch("GITHUB_TOKEN"), # The GitHub token to use
+    issue_number: 123 # The issue number to use
+)
+
+# Now you have an octokitted client that is hydrated and ready to use just as seen in the more detailed example above!
+
+puts "#{gh.org} #{gh.repo} #{gh.org_and_repo}"
+# => GrantBirki octokitted GrantBirki/octokitted
+
+puts gh.issue_number
+# => 123
+
+# ...
+```
+
+### Native Git Usage
+
+If you system / container has the `git` binary installed, you can also use this Gem to run native Git commands:
+
+```ruby
+# frozen_string_literal: true
+
+require "octokitted"
+
+# Setup a new instance of Octokitted with explicit values
+gh = Octokitted.new(
+    login: "GrantBirki", # The user associated with the GITHUB_TOKEN
+    org: "GrantBirki", # The organization associated with the repo
+    repo: "octokitted", # The repo name
+    token: ENV.fetch("GITHUB_TOKEN") # The GitHub token to use
+)
+
+# Check to see if there are any cloned repos
+puts gh.cloned_repos
+# => []
+
+# Clone the repo we setup our client with and get back a Git::Base object
+git = gh.clone
+
+# Check again to see that we have one locally cloned repo at the path displayed
+puts gh.cloned_repos
+# => ["./octokitted"]
+
+git.checkout("new_branch", new_branch: true, start_point: "main")
+
+git.add # git add -- "."
+# git.add(:all=>true) # git add --all -- "."
+# git.add("file_path") # git add -- "file_path"
+# git.add(["file_path_1", "file_path_2"])
+
+git.commit("message")
+# git.commit_all("message")
+
+git.push
+# git.push(git.remote("name"))
+
+# remove the repo we just cloned
+gh.remove_all_clones!
+
+puts gh.cloned_repos
+# => []
+```
+
+> Read more about the native Git Ruby Gem [here](https://github.com/ruby-git/ruby-git)
+
+## Release 🚀
+
+To release a new version of this gem, simply edit the [`lib/version.rb`](lib/version.rb) in this repo. When you commit your changes to `main`, a new version will be automatically released via GitHub Actions to RubyGems and GitHub Packages.

data/lib/octokitted/common/issue.rb

@@ -43,8 +43,8 @@ class Issue
   # Adds a comment to an issue or pull request
   # :param comment: The comment to add to the issue (String)
   # :param issue_number: The issue number to add the comment to
-  Contract KeywordArgs[comment: String, issue_number: Maybe[Numeric]] => Any
-  def add_comment(comment:, issue_number: nil)
+  Contract String, KeywordArgs[issue_number: Maybe[Numeric]] => Any
+  def add_comment(comment, issue_number: nil)
     issue_number = construct_issue_numer(issue_number)
     @log.debug("adding comment: #{comment} to issue: #{issue_number}")
 

data/lib/octokitted.rb

@@ -62,6 +62,15 @@ class Octokitted
     @log.debug("repo: #{@repo}")
   end
 
+  # Setter method for the issue_number instance variable
+  # :param issue_number: The issue_number to set
+  # :return: it does not return as it is a setter method
+  Contract Numeric => Any
+  def issue_number=(issue_number)
+    @issue_number = issue_number
+    @log.debug("updated issue_number: #{@issue_number}")
+  end
+
   # Setter method for the repo instance variable
   # :param repo: The repo to set
   # :return: it does not return as it is a setter method
@@ -184,6 +193,11 @@ class Octokitted
 
     issue_number = (github_event[:issue] || github_event[:pull_request] || github_event)[:number]
 
+    if issue_number.nil?
+      @log.debug("issue_number not found in GitHub event data - issue_number not auto-hydrated")
+      return nil
+    end
+
     @log.info("issue_number auto-hydrated - issue_number: #{issue_number}")
     return issue_number
   end

data/lib/version.rb

@@ -2,6 +2,6 @@
 
 module Octokitted
   module Version
-    VERSION = "0.0.9"
+    VERSION = "1.0.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: octokitted
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 1.0.1
 platform: ruby
 authors:
 - Grant Birkinbine
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-27 00:00:00.000000000 Z
+date: 2023-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: contracts