issue-db 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 740a1a64de7f9ab45fd7932682999972139392b4c8d8f48105cde4f49e9474b1
-  data.tar.gz: 6219653cb7f2303482e039f906ae788e4d9f9a89131df12e750ef35cc0f8a976
+  metadata.gz: 8c165f569fbb2648a4c73a0bf4007f67e6da2ff2dae28132af424d9eb9844575
+  data.tar.gz: 224bc98fcc029e417e620e4d8efaa79030fdf1a767558d126ab22145fec66ac7
 SHA512:
-  metadata.gz: 743c37f2ca18320e7ce68f4c5f88b2275a19c93f2239d10c7a1b5102ffb089444fb79ca947efef6dd47792bfeeafe82ead49812e92605f2ccafa0b351ce9ac43
-  data.tar.gz: cb0eb761ee2dfa89c3fc0f8d096957269905052778756a09fc755c3a5975264c690e725e38f707e4a10be618e8255f6b2cde26d1755d4ddac3d06c919e7499b7
+  metadata.gz: e870e848ab6765beb5470008c38c03c9d0133fa22c9bd74a93888bbef7e59fb001dc18f9311106bdc8e43c4ef442eeb8f9f18fd8e18df37fcc7f9e9e5e4a1ad2
+  data.tar.gz: 5932e25bbc9bd9f1bf68638d38b61675ac5a497c4cc2fc2e59e121bdc838a3c2759d45a32c3e47014c8e88f6000116d33227379336fc3fbe1370107a4613402f

data/README.md

@@ -88,6 +88,23 @@ record = db.create("order_number_123", { location: "London", items: [ "cookies",
 # more on this in another section of the README below
 options = { body_before: "some markdown text before the data", body_after: "some markdown text after the data" }
 record = db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] }, options)
+
+# with the `labels` option to add additional GitHub labels to the issue (in addition to the library-managed label)
+options = { labels: ["priority:high", "customer:premium"] }
+record = db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] }, options)
+
+# with the `assignees` option to assign GitHub users to the issue
+options = { assignees: ["alice", "bob"] }
+record = db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] }, options)
+
+# with multiple options combined
+options = { 
+  labels: ["priority:high", "customer:premium"],
+  assignees: ["alice", "bob"],
+  body_before: "some markdown text before the data", 
+  body_after: "some markdown text after the data" 
+}
+record = db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] }, options)
 ```
 
 Notes:
@@ -125,6 +142,23 @@ record = db.update("order_number_123", { location: "London", items: [ "cookies",
 # more on this in another section of the README below
 options = { body_before: "# Order 123\n\nData:", body_after: "Please do not edit the body of this issue" }
 record = db.update("order_number_123", { location: "London", items: [ "cookies", "espresso", "chips" ] }, options)
+
+# with the `labels` option to add additional GitHub labels to the issue (in addition to the library-managed label)
+options = { labels: ["status:processed", "priority:low"] }
+record = db.update("order_number_123", { location: "London", items: [ "cookies", "espresso", "chips" ] }, options)
+
+# with the `assignees` option to assign GitHub users to the issue
+options = { assignees: ["charlie", "diana"] }
+record = db.update("order_number_123", { location: "London", items: [ "cookies", "espresso", "chips" ] }, options)
+
+# with multiple options combined
+options = { 
+  labels: ["status:processed", "priority:low"],
+  assignees: ["charlie", "diana"],
+  body_before: "# Order 123\n\nData:", 
+  body_after: "Please do not edit the body of this issue" 
+}
+record = db.update("order_number_123", { location: "London", items: [ "cookies", "espresso", "chips" ] }, options)
 ```
 
 ### `db.delete(key, options = {})`
@@ -136,6 +170,21 @@ Example:
 
 ```ruby
 record = db.delete("order_number_123")
+
+# with the `labels` option to add additional GitHub labels to the issue before closing it
+options = { labels: ["archived", "completed"] }
+record = db.delete("order_number_123", options)
+
+# with the `assignees` option to assign GitHub users to the issue before closing it
+options = { assignees: ["alice"] }
+record = db.delete("order_number_123", options)
+
+# with multiple options combined
+options = { 
+  labels: ["archived", "completed"],
+  assignees: ["alice"]
+}
+record = db.delete("order_number_123", options)
 ```
 
 ### `db.list_keys(options = {})`
@@ -195,6 +244,153 @@ This section will go into detail around how you can configure the `issue-db` gem
 | `GH_APP_ALGO` | The algo to use for your GitHub App if providing a private key | `RS256` |
 | `ISSUE_DB_GITHUB_TOKEN` | The GitHub personal access token to use for authenticating with the GitHub API. You can also use a GitHub app or pass in your own authenticated Octokit.rb instance | `nil` |
 
+## Labels 🏷️
+
+The `issue-db` gem uses GitHub issue labels for organization and management. Here's how labels work:
+
+### Library-Managed Label
+
+The gem automatically applies a library-managed label (default: `issue-db`) to all issues it creates. This label:
+
+- **Cannot be modified or removed** by users (the gem will always ensure it's present)
+- Is used to identify which issues in the repository are managed by the `issue-db` gem
+- Can be customized by setting the `ISSUE_DB_LABEL` environment variable or passing the `label` parameter to `IssueDB.new()`
+
+### Additional Custom Labels
+
+You can add your own custom labels to issues when creating, updating, or deleting records by using the `labels` option:
+
+```ruby
+# Add custom labels when creating a record
+options = { labels: ["priority:high", "customer:premium", "region:europe"] }
+record = db.create("order_123", { product: "laptop" }, options)
+
+# Add custom labels when updating a record
+options = { labels: ["status:processed", "priority:low"] }
+record = db.update("order_123", { product: "laptop", status: "shipped" }, options)
+
+# Add custom labels before deleting (closing) a record
+options = { labels: ["archived", "completed", "Q4-2024"] }
+record = db.delete("order_123", options)
+```
+
+**Important Notes:**
+
+- Custom labels are **added in addition** to the library-managed label, not instead of it
+- If you accidentally include the library-managed label in your custom labels array, it will be automatically filtered out to prevent duplicates
+- Custom labels follow GitHub's label naming conventions and restrictions
+- Labels help with organization, filtering, and automation workflows in GitHub
+
+### Label Preservation
+
+When performing update or delete operations, the gem preserves existing labels by default:
+
+```ruby
+# Create a record with custom labels
+options = { labels: ["priority:high", "customer:premium"] }
+record = db.create("order_123", { product: "laptop" }, options)
+# Result: Issue has labels ["issue-db", "priority:high", "customer:premium"]
+
+# Update the record WITHOUT specifying labels - existing labels are preserved
+record = db.update("order_123", { product: "laptop", status: "shipped" })
+# Result: Issue STILL has labels ["issue-db", "priority:high", "customer:premium"]
+
+# Update the record WITH new labels - replaces all labels (except library-managed)
+options = { labels: ["status:processed", "priority:low"] }
+record = db.update("order_123", { product: "laptop", status: "delivered" }, options)
+# Result: Issue now has labels ["issue-db", "status:processed", "priority:low"]
+```
+
+**Key Behavior:**
+
+- **Labels specified** = Replace all labels with library-managed label + specified labels
+- **No labels specified** = Preserve existing labels exactly as they are
+
+### Example with Multiple Options
+
+You can combine labels with other options:
+
+```ruby
+options = {
+  labels: ["priority:high", "customer:vip"],
+  body_before: "## Order Details\n\nCustomer: VIP\n\n",
+  body_after: "\n\n---\n*This order requires special handling*"
+}
+record = db.create("vip_order_456", { items: ["premium_service"] }, options)
+```
+
+## Assignees 👥
+
+The `issue-db` gem supports GitHub issue assignees for task ownership and responsibility tracking. Here's how assignees work:
+
+### Basic Assignee Usage
+
+You can assign GitHub users to issues when creating, updating, or deleting records by using the `assignees` option:
+
+```ruby
+# Assign users when creating a record
+options = { assignees: ["alice", "bob"] }
+record = db.create("task_123", { type: "code_review" }, options)
+
+# Assign users when updating a record
+options = { assignees: ["charlie", "diana"] }
+record = db.update("task_123", { type: "code_review", status: "in_progress" }, options)
+
+# Assign users before deleting (closing) a record
+options = { assignees: ["alice"] }
+record = db.delete("task_123", options)
+```
+
+### Assignee Preservation
+
+Just like labels, the gem preserves existing assignees by default when no assignees are specified:
+
+```ruby
+# Create a record with assignees
+options = { assignees: ["alice", "bob"] }
+record = db.create("task_123", { type: "code_review" }, options)
+# Result: Issue is assigned to alice and bob
+
+# Update the record WITHOUT specifying assignees - existing assignees are preserved
+record = db.update("task_123", { type: "code_review", status: "in_progress" })
+# Result: Issue is STILL assigned to alice and bob
+
+# Update the record WITH new assignees - replaces all assignees
+options = { assignees: ["charlie"] }
+record = db.update("task_123", { type: "code_review", status: "completed" }, options)
+# Result: Issue is now only assigned to charlie
+```
+
+**Key Behavior:**
+
+- **Assignees specified** = Replace all assignees with the specified assignees
+- **No assignees specified** = Preserve existing assignees exactly as they are
+- **Empty array specified** = Remove all assignees from the issue
+
+### Combining Labels and Assignees
+
+You can use both labels and assignees together for comprehensive issue management:
+
+```ruby
+options = {
+  labels: ["priority:high", "type:bug", "team:backend"],
+  assignees: ["alice", "bob"],
+  body_before: "## Bug Report\n\nPriority: High\nTeam: Backend\n\n",
+  body_after: "\n\n---\n*Assigned to backend team leads*"
+}
+record = db.create("bug_456", { 
+  error: "Database timeout", 
+  severity: "critical" 
+}, options)
+```
+
+**Important Notes:**
+
+- Assignees must be valid GitHub usernames with access to the repository
+- You can assign up to 10 users to a single issue (GitHub's limit)
+- Invalid or inaccessible usernames will cause the API call to fail
+- Assignees help with responsibility tracking, notifications, and project management workflows
+
 ## Authentication 🔒
 
 The `issue-db` gem uses the [`Octokit.rb`](https://github.com/octokit/octokit.rb) library under the hood for interactions with the GitHub API. You have four options for authentication when using the `issue-db` gem:

data/lib/issue_db/database.rb

@@ -31,11 +31,11 @@ module IssueDB
     # This will return the newly created issue as a Record object (parsed)
     # :param: key [String] the key (issue title) to create
     # :param: data [Hash] the data to use for the issue body
-    # :param: options [Hash] a hash of options containing extra data such as body_before and body_after
+    # :param: options [Hash] a hash of options containing extra data such as body_before, body_after, labels, and assignees
     # :return: The newly created issue as a Record object
     # usage example:
     # data = { color: "blue", cool: true, popularity: 100, tags: ["tag1", "tag2"] }
-    # options = { body_before: "some text before the data", body_after: "some text after the data", include_closed: true }
+    # options = { body_before: "some text before the data", body_after: "some text after the data", include_closed: true, labels: ["priority:high", "bug"], assignees: ["username1", "username2"] }
     # db.create("event123", {cool: true, data: "here"}, options)
     def create(key, data, options = {})
       @log.debug("attempting to create: #{key}")
@@ -49,8 +49,24 @@ module IssueDB
 
       body = generate(data, body_before: options[:body_before], body_after: options[:body_after])
 
+      # Prepare labels array - always include the library-managed label for create operations
+      labels = [@label]
+      if options[:labels] && options[:labels].is_a?(Array)
+        # Add user-provided labels but ensure the library label is not duplicated
+        user_labels = options[:labels].reject { |label| label == @label }
+        labels.concat(user_labels)
+      end
+
+      # Prepare API options hash
+      api_options = { labels: labels }
+
+      # Add assignees if provided
+      if options[:assignees] && options[:assignees].is_a?(Array)
+        api_options[:assignees] = options[:assignees]
+      end
+
       # if we make it here, no existing issues were found so we can safely create one
-      issue = @client.create_issue(@repo.full_name, key, body, { labels: @label })
+      issue = @client.create_issue(@repo.full_name, key, body, api_options)
 
       # ensure the cache is initialized before appending and handle race conditions
       current_issues = issues
@@ -78,11 +94,11 @@ module IssueDB
     # This will return the updated issue as a Record object (parsed)
     # :param: key [String] the key (issue title) to update
     # :param: data [Hash] the data to use for the issue body
-    # :param: options [Hash] a hash of options containing extra data such as body_before and body_after
+    # :param: options [Hash] a hash of options containing extra data such as body_before, body_after, labels, and assignees
     # :return: The updated issue as a Record object
     # usage example:
     # data = { color: "blue", cool: true, popularity: 100, tags: ["tag1", "tag2"] }
-    # options = { body_before: "some text before the data", body_after: "some text after the data", include_closed: true }
+    # options = { body_before: "some text before the data", body_after: "some text after the data", include_closed: true, labels: ["priority:high", "bug"], assignees: ["username1", "username2"] }
     # db.update("event123", {cool: true, data: "here"}, options)
     def update(key, data, options = {})
       @log.debug("attempting to update: #{key}")
@@ -90,7 +106,25 @@ module IssueDB
 
       body = generate(data, body_before: options[:body_before], body_after: options[:body_after])
 
-      updated_issue = @client.update_issue(@repo.full_name, issue.number, key, body)
+      # Prepare the API call options
+      api_options = {}
+
+      # Only modify labels if the user explicitly provides them
+      if options[:labels] && options[:labels].is_a?(Array)
+        # Prepare labels array - always include the library-managed label
+        labels = [@label]
+        # Add user-provided labels but ensure the library label is not duplicated
+        user_labels = options[:labels].reject { |label| label == @label }
+        labels.concat(user_labels)
+        api_options[:labels] = labels
+      end
+
+      # Only modify assignees if the user explicitly provides them
+      if options[:assignees] && options[:assignees].is_a?(Array)
+        api_options[:assignees] = options[:assignees]
+      end
+
+      updated_issue = @client.update_issue(@repo.full_name, issue.number, key, body, api_options)
 
       # update the issue in the cache using the reference we have
       index = @issues.index(issue)
@@ -108,15 +142,34 @@ module IssueDB
 
     # Delete an issue/record from the database - in this context, "delete" means to close the issue as "completed"
     # :param: key [String] the key (issue title) to delete
-    # :param: options [Hash] a hash of options to pass through to the search method
+    # :param: options [Hash] a hash of options to pass through to the search method and control labels and assignees
     # :return: The deleted issue as a Record object (parsed) - it may contain useful data
     def delete(key, options = {})
       @log.debug("attempting to delete: #{key}")
       issue = find_issue_by_key(key, options)
 
-      deleted_issue = @client.close_issue(@repo.full_name, issue.number)
+      # For delete operations, only update labels and assignees if the user explicitly provides them
+      if (options[:labels] && options[:labels].is_a?(Array)) || (options[:assignees] && options[:assignees].is_a?(Array))
+        update_options = {}
+
+        if options[:labels] && options[:labels].is_a?(Array)
+          # Prepare labels array - always include the library-managed label
+          labels = [@label]
+          # Add user-provided labels but ensure the library label is not duplicated
+          user_labels = options[:labels].reject { |label| label == @label }
+          labels.concat(user_labels)
+          update_options[:labels] = labels
+        end
+
+        if options[:assignees] && options[:assignees].is_a?(Array)
+          update_options[:assignees] = options[:assignees]
+        end
+
+        # Update the issue with new labels and/or assignees before closing
+        @client.update_issue(@repo.full_name, issue.number, update_options)
+      end
 
-      # update the issue in the cache using the reference we have
+      deleted_issue = @client.close_issue(@repo.full_name, issue.number)      # update the issue in the cache using the reference we have
       index = @issues.index(issue)
       if index
         @issues[index] = deleted_issue
@@ -126,6 +179,7 @@ module IssueDB
         update_issue_cache!
       end
 
+      @log.debug("issue deleted: #{key}")
       # return the deleted issue as a Record object as it may contain useful data
       return Record.new(deleted_issue)
     end

data/lib/version.rb

@@ -2,6 +2,6 @@
 
 module IssueDB
   module Version
-    VERSION = "1.2.0"
+    VERSION = "1.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: issue-db
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - runwaylab