issuer 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b9eef4a9d197d93d73741916ac3b33667eeedbd8f2bdc4bb7efc15a81bace2f
-  data.tar.gz: d638d611dfece68b9a9492be2a8355b14603aabf4f70e6d2212b9b73b3085775
+  metadata.gz: 4fd7532708ed57245a8e2721d299cd2931c24737da8a156bd238cc5977e4691c
+  data.tar.gz: 7f277c821b7fe8bb7eda03b5e85718202409fe54bd84d8b4e50bb8911fcce337
 SHA512:
-  metadata.gz: 5dd29f7a22ef465afa9888dd4342c46f838298598d79ef0008f0567103030ea45a4fb3882c47460730486a4d5da4794d321fd25db9fc588e4e0a64c023fd67c4
-  data.tar.gz: 1d47716be2e67809b08dee0e11a65ef32f87f8ba1a61291759b958c6f7ab9f357fbad8b80ea5a567cf643e9f6721527c9b57e6ee5bbc9f0c373dff306cc609ed
+  metadata.gz: 381f003520f2c514445bbea944589839a189fa3afee7126d0567d61d680b1a4b79b407886db97749e1cdf9efcb2bb46679e33002700604ed64fa054ee8bcc245
+  data.tar.gz: ff486e3bc512907226b7f4fadf454f091cf853dad7c1492f0d5e410b82a3b4584d63a6a817c5fbe6c8d3437770b3ad59ba1b78070cac3cc4559996df6fb75f3a

data/README.adoc

@@ -1,18 +1,23 @@
 = Issuer: Bulk GitHub Issue Creator
 :toc: macro
 :toclevels: 3
-:this_prod_vrsn: 0.1.1
-:next_prod_vrsn: 0.2.0
-:docker_base_command: docker run -it --rm -v $(pwd):/workdir -e GITHUB_TOKEN=$ISSUER_API_TOKEN docopslab/issuer
+:this_prod_vrsn: 0.2.1
+:next_prod_vrsn: 0.3.0
+:docker_base_command: docker run -it --rm -v $(pwd):/workdir -e ISSUER_API_TOKEN=$GITHUB_TOKEN docopslab/issuer
 :append_or_impose: Prepend items with `+` to indicate they should be appended to existing labels. Items without `+` will only be used for issues with no `tags` designated.
 ifdef::env-github[]
 :icons: font
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
 endif::[]
 
 
 == Overview
 
-_Issuer_ lets you define all your work tickets in one place as YAML, apply defaults, and post them to GitHub Issues in bulk.
+_Issuer_ lets you define all your GitHub Issues work tickets in one place as YAML, apply defaults, and post them to GitHub Issues in bulk.
 
 === Features
 
@@ -22,12 +27,26 @@ _Issuer_ lets you define all your work tickets in one place as YAML, apply defau
 * *Configurable defaults* and label application
 * *Environment variable support* for authentication
 * *Issue validation* with helpful error messages
-* *GitHub API integration* via Octokit
+* *GitHub API integration*
 
-Future plans include extending this capability to *JIRA*, *GitLab* Issues, GitHub *Projects*, and other services.
+Future plans include extending this capability to *Jira* (link:https://github.com/DocOps/issuer/issues/9[#9]), *GitLab* Issues (link:https://github.com/DocOps/issuer/issues/33[#33]), GitHub *Projects*, and other services.
 
 toc::[]
 
+=== Who Is This For?
+
+This tool is oriented as much for _project managers_ as it is for _software developers_, but the target audience is probably *people who manage software development cycles*, especially using Git tools and GitHub Issues (or soon Jira Issues and GitLab Issues).
+
+[NOTE]
+Issuer does not require Git be installed on your local workstation.
+The only direct use of Git would be if you commit and share the batch-configuration file with your team for collective editing.
+
+This tool is great at creating "`stub`" issues for entire teams, based on user-story documents, task lists, or other planning documents.
+Once you convert such documents to our special YAML-based definition format (IMYML), use `issuer` to post them to your GitHub Issues system via GitHub's API.
+
+Individual issue entries can be as basic or as detailed as you wish.
+They may consist of as little as just a title (summary) line, or that plus an assignee responsible for filling out the rest and adding metadata.
+Or they can be complete with labels, milestones, a type designation, and a complete explanation of the issue.
 
 == Installation
 
@@ -57,15 +76,18 @@ With Docker installed and running...
 For actual issue creation, use something like:
 
 [.prompt,subs=+attributes]
- {docker_base_command} your-issues.yml --dry
+ {docker_base_command} your-issues.yml
 
 The above command:
 
 * mounts your local directory to be readable by the Docker container
-* passes your GitHub access token environment variable into the container (`$ISSUER_API_TOKEN` could be `$ISSER_GITHUB_TOKEN`, `$GITHUB_ACCESS_TOKEN`, or `$GITHUB_TOKEN`).
+* passes your GitHub access token environment variable into the container (`$ISSUER_API_TOKEN` could be `$ISSUER_GITHUB_TOKEN`, `$GITHUB_ACCESS_TOKEN`, or `$GITHUB_TOKEN`).
+* connects to GitHub and creates issue entries one at a time from `your-issues.yml`
 
 Everything after `docopslab/issuer` accepts the standard arguments and options of the issuer CLI.
 
+See <<usage>> for more.
+
 [[docker-alias]]
 ==== Alias the Docker Command
 
@@ -82,7 +104,7 @@ Reload your shell configuration for the alias to take effect:
 
 === For Ruby Users
 
-If you have Ruby on your workstation, there are two common ways to install thi gem.
+If you have Ruby on your workstation, there are two common ways to install this gem.
 
 ==== Global Installation
 
@@ -91,7 +113,7 @@ If you have Ruby on your workstation, there are two common ways to install thi g
 
 Then you can use the `issuer` command from anywhere in your system.
 
-==== Local/Applicaition Installation
+==== Local/Application Installation
 
 Add this line to your Gemfile:
 
@@ -106,14 +128,14 @@ And then execute:
 
 Now you can use `bundle exec issuer` to perform operations inside the project directory.
 
-
+[[usage]]
 == Usage
 
 Once installed, you can start using `issuer` to create issues in GitHub.
 
 === Quickstart Overview
 
-The following steps assume the gem is either installed globally or `issuer` is <<docker-alias,established as an alias>>.
+The following steps assume the gem is either installed globally or `issuer` is <<docker-alias,established as an alias>> (Docker method).
 For Ruby Bundler usage, prepend `bundle exec ` and for un-aliased Docker usage, prepend `{docker_base_command}`.
 
 . Prepare your issue definitions in an IMYML file (see <<imyml-format,examples and docs>> below).
@@ -122,7 +144,7 @@ For Ruby Bundler usage, prepend `bundle exec ` and for un-aliased Docker usage,
 +
  issuer example.yml --dry
 
-. Establish a Personal Access Token for GitHub (see <<authentication,Authentication>> below).
+. Establish a Personal Access Token for GitHub and store it as an environment variable (see <<authentication>> below).
 
 . Post issues to GitHub:
 +
@@ -143,7 +165,8 @@ $meta: # optional block for establishing general modes/settings
   defaults: # value to infer when given property missing
     vrsn: 0.1.0 # milestone/version
     user: alice # assigned user
-    tags: [needs_labels,+posted_by_issuer] # labels
+    type: Bug # type of issue (must already be registered)
+    tags: [needs:labels, +posted_by_issuer, +needs:docs] # labels
     stub: true # whether to auto-insert stub texts
     head: | # header stub text to prepend when indicated
       Below the next line is the body...
@@ -152,9 +175,10 @@ $meta: # optional block for establishing general modes/settings
       ---
       This issue was automatically generated by issuer. 
     body: | # body text to impose when no body provided
-      This is the default text that will appear if an issue record is a _stub_ and no `body` field is designated. 
+      This is the default text that will appear if an issue record is a _stub_ and no `body` field is designated.
 issues: # block for listing issues to post to cloud
   - summ: Issue title # title/summary field
+    type: Task # type of issue (must already be registered)
     body: | # description/body field
       Markdown-formatted description.
     tags: [label1, 'component:api'] # labels to create/assign
@@ -167,14 +191,20 @@ issues: # block for listing issues to post to cloud
     # ---
     # This is the default text that will appear if an issue record is a _stub_ and no `body` field is designated.
     # ---
-    # This issue was automatically generated by issuer. 
+    # This issue was automatically generated by issuer.
+  - summ: Documentation issue
+    tags: [-needs:docs] # skip the default needs:docs label
 ----
 
 The `$meta` block is entirely optional, but if it is absent, your `issuer` command will need a `--proj` flag to designate the GitHub repo to which your issues should post.
 
-Only the `summ` property is required for each issue record, and issue records (Array items) that are simple strings that will be treated as summary-only.
+Only the `summ` property is required for each issue record, and issue records (Array items) that are simple strings will be treated as summary-only.
 Therefore, the following example would yield 3 tickets with unique summaries and the same body, based on `$meta.defaults.body`.
 
+Issuer will prompt the creation of tags (labels) or versions (milestones) if they do not already exist in the target repository.
+
+Any `type` entry must correspond to an existing issue type.
+
 [source,yaml]
 ----
 $meta:
@@ -192,83 +222,102 @@ issues:
 ----
 
 [TIP]
-This repository contains numerous link:lib/examples/README.adoc[example files] to use for inspiration.
+This repository contains numerous link:examples/README.adoc[example files] to use for inspiration.
 
 The IMYML format will be standardized and formally specified in a future release of _issuer_, but it will remain an _open standard_ adoptable by anyone who wants to exploit or extend it.
 
 [[imyml-ref]]
 ==== IMYML Properties Reference
 
-`$meta`::
+$meta::
 Optional block for establishing operation-wide modes and settings.
 
-`$meta.proj`:::
+$meta.proj:::
 (String)
 Designates the target project/repository.
 
-`$meta.defaults`:::
-Designates the default values to use for any issue record that does not specify a value for a given property.
+$meta.defaults:::
+Properties in this block establish the default values to be used for any issue record that does not specify a value for the given property.
 
-`$meta.defaults.vrsn`::::
+$meta.defaults.vrsn::::
 (String)
 Sets default version or milestone for all issues.
 
-`$meta.defaults.user`::::
+$meta.defaults.user::::
 (String)
 Sets default assignee (GitHub username).
 
-`$meta.defaults.tags`::::
+$meta.defaults.type::::
+(String)
+Sets default issue type to apply to all issues when no `type` property is specified in the issue record.
+
+$meta.defaults.tags::::
 (Array):
 Labels to append to issues (comma-separated).
 {append_or_impose}
 
-`$meta.defaults.stub`::::
+$meta.defaults.stub::::
 (Boolean)
 Establishes the state whether to insert stub texts (`body` / `head` / `tail`).
 
-`$meta.defaults.body`::::
+$meta.defaults.body::::
 (String)
 Sets default body text to apply to all issues when no `body` property is specified in the issue record.
 
-`$meta.defaults.head`::::
+$meta.defaults.head::::
 (String)
 Sets default text to insert before the body of all issues for which `stub`.
 
-`$meta.defaults.tail`::::
+$meta.defaults.tail::::
 (String)
 Sets default text to insert after the body of all issues for which `stub`.
 
-`issues`::
-(Array) Tabular listing of issue records as Array itmes.
+issues::
+(Array)
+Tabular listing of *issue records* as Array items.
 If an item is Scalar (not a Map with named keys), the value must be a String and it will be treated as the `summ` (summary/title) property.
 +
 Otherwise, any `issues` Array items must be Map-formatted "`dictionaries`" with the following properties:
 
-`summ`:::
+summ:::
 (String, *required*)
 A one-line title or summary of the issue.
 
-`body`:::
+body:::
 (String)
 The main body or description text for the issue.
 Defaults to `$meta.defaults.body` if `stub == true` for the record, in which case, upon submission, will also incorporate any values for `$meta.defaults.head` and `$meta.defaults.tail`.
 
-`vrsn`:::
+vrsn:::
 (String)
 The milestone associated with the issue.
 +
 Defaults to `$meta.defaults.vrsn` or else `null`.
 
-`tags`:::
+type:::
+(String)
+The type of issue, which must already be registered in the target project or repository.
+Defaults to `$meta.defaults.type` or else `null`.
+
+tags:::
 (Array of Strings)
 A listing of specific labels to assign to the issue.
++
+Supports special prefix notation for label management:
++
+* Regular labels (example: `bug`, `priority:high`) are applied based on default tag logic
+* Append labels (example: `+urgent`) are always applied to all issues
+* Removal labels (example: `-needs:docs`) remove the specified label from the default/appended labels list
++
+Example: `tags: [documentation, +critical, -needs:review]` would add `documentation` and `critical` labels while removing any `needs:review` label from defaults.
 
-`user`:::
+user:::
 (String)
 The system username of the person or bot to which the ticket is assigned.
 
-`stub [true+++*+++|false]`:::
+stub:::
 (Boolean)
+Accepts `true` or `false`.
 Whether to treat the issue as a stub entry, meaning prepend any `$meta.defaults.head` text or append any `$meta.defaults.tail` text, and in case the ticket has no `body` property, insert the text of `$meta.defaults.body`.
 
 [[cli-usage]]
@@ -301,13 +350,13 @@ IMYML file path (alternative to positional argument).
 The target project (org/repo or user/repo format for GitHub).
 
 --vrsn _VERSION_::
-Argues default milestone for all issues.
+Sets default milestone for all issues.
 
 --user _USERNAME_::
-Argues default assignee (GitHub username).
+Sets default assignee (GitHub username).
 
 --tags _TAG_[,_TAG_]::
-Argues labels to impose or add issues (comma-separated).
+Sets labels to apply to issues (comma-separated).
 {append_or_impose}
 
 --stub [_true_+++*+++|_false_]::
@@ -315,7 +364,7 @@ Whether to treat all issues as stubs, meaning prepend any `$meta.defaults.head`
 
 ==== Mode Options
 
---dry::
+--dry, --dry-run::
 Dry-run: print actions but do not post to GitHub.
 
 --auto-versions, --auto-milestones::
@@ -327,7 +376,7 @@ Automatically create missing labels/tags without prompting for confirmation.
 --auto-metadata::
 Automatically create all missing metadata (milestones and labels) without prompting for confirmation. Equivalent to using both `--auto-versions` and `--auto-tags`.
 
---help::
+--help, -h::
 Prints the usage screen.
 
 --version::
@@ -348,7 +397,7 @@ The application will check for environment variables in the following order:
 To *create and set a token*:
 
 . In the GitHub Web interface, go to *Settings* (under your user icon) → *Developer Settings* (bottom of left menu) → *Personal Access Tokens* → *Fine-grained tokens*.
-. Generate a new token with access to *All repositoriess* or any *Select repositories* you wish to post to, and include read/write permissions GitHub Issues (under *Repository permissions*).
+. Generate a new token with access to *All repositories* or any *Select repositories* you wish to post to, and include read/write permissions GitHub Issues (under *Repository permissions*).
 . Copy the token and set it as an environment variable.
 +
 .Example
@@ -356,6 +405,13 @@ To *create and set a token*:
 +
 Where `github_pat_xxxxxxxxxxxxxxxxxxxxxxxx` is your actual token.
 
+If your GitHub token is stored under *any other name*, you can alias it inline by prepending to your `issuer` command.
+For example:
+
+ ISSUER_API_TOKEN=$MY_GITHUB_API_KEY issuer my-issues.yml
+
+When using Docker, you can pass any such key into the container this way, using the `-e` option: `-e ISSUER_API_TOKEN=$MY_GITHUB_API_KEY`.
+
 
 == Advanced Usage
 
@@ -416,19 +472,19 @@ Logs are simply kept for easy reversal of mis-postings.
 I developed the 0.1.0 version of this application after trying to use GitHub Copilot to automatically bulk-create issue tickets, which it promises to be able to do but failed me pretty hard at it.
 
 That facility seems like a perfectly inappropriate use of generative AI.
-It accepted my plan request and pre-drafted ticket content, but then it wanted me to manually add labels and milestones to them, as well as manually click *create* on each one -- even though I had already taken the time to plan and instruct the milestones and labels and the contents were fullly prepared.
+It accepted my plan request and pre-drafted ticket content, but then it wanted me to manually add labels and milestones to them, as well as manually click *create* on each one -- even though I had already taken the time to plan and instruct the milestones and labels and the contents were fully prepared.
 
-Additionally, I find myself using different issue-management systems (JIRA, GitLab Issues, etc), so I wanted a more platform-agnostic way to handle this problem.
+Additionally, I find myself using different issue-management systems (Jira, GitLab Issues, etc), so I wanted a more platform-agnostic way to handle this problem.
 With that in mind, I have left the Ruby API and the IMYML model fairly "`generic`" for extensibility.
 I will probably adapt the API to other systems in future releases, and I welcome <<contributing,contributions>> to that effect.
 
 === Methodology Confession
 
-I should note up front that this is the closest I have come to "`vibe coding`" anything bigger than a local script, let alone a shippable production code.
-Nevertheless, I intervened to make substantial and specific changes at least 100 times, and I rearranged major aspects of the codebase.
+I should note up front that this is the closest I have come to "`vibe coding`" anything bigger than a local script, let alone shippable production code.
+Nevertheless, I intervened to make substantial and specific changes at least 100 times before the 0.1.0 release alone, and I rearranged major aspects of the codebase.
 
-I designed the IMYML format and the CLI up front, then I let Claud 4 (via GH Copilot) draft most of the code.
-It committed lots of rookie mistakes during this process, and it even confessed to "`cargo-cult programming`" when I pointed out it was introduing some anti-patterns.
+I designed the IMYML format and the CLI up front, then I let Claude 4 (via GH Copilot) draft most of the code.
+It committed lots of rookie mistakes during this process, and it even confessed to "`cargo-cult programming`" when I pointed out it was introducing some anti-patterns.
 
 In the end, the only thing that is mainly untouched by me are the rspec tests, which I will more fully examine and approve before any 1.0 release, but for now they'll have to do.
 
@@ -479,10 +535,10 @@ bundle exec rspec --pattern "*ops*"
 
 The `pr_test` task runs the exact same tests that GitHub Actions runs for pull requests:
 
-* **RSpec Tests**: All unit tests (`bundle exec rake spec`)
-* **CLI Tests**: Command-line interface functionality tests
-* **YAML Validation**: Validates all example YAML files
-* **Documentation Quality**: Vale linting on all documentation files
+* *RSpec Tests*: All unit tests (`bundle exec rake spec`)
+* *CLI Tests*: Command-line interface functionality tests
+* *YAML Validation*: Validates all example YAML files
+* *Documentation Quality*: Vale linting on all documentation files
 
 This ensures you can validate your changes locally before pushing to GitHub.
 
@@ -528,6 +584,47 @@ The GitHub API test suite validates:
 * Automation flags (`--auto-metadata`, `--auto-versions`, etc.)
 * Error handling and edge cases
 
+=== API Reference
+
+For detailed API documentation, see the automatically generated documentation at https://gemdocs.org/gems/issuer/{this_prod_vrsn}[GemDocs].
+
+The API reference includes:
+
+* Complete class and method documentation
+* Method signatures and parameters
+* Return types and examples
+* Internal implementation details
+
+This documentation is automatically updated with each gem release.
+
+=== Release History Management
+
+As of version 0.2.0, the Release Notes and Changelog are generated using the _ReleaseHx_ tool, which is still in pre-release.
+You can find the release history assets in the `docs/releasehx/` directory, which contains a configuration file and the 0.2.0 "`RHYML`" file that was auto-modified and then manually edited to produce the GitHub link:https://github.com/DocOps/issuer/releases[release announcement].
+
+ReleaseHx will be available soon, but for now the following is only usable by DocOps Lab.
+
+. Add local releasehx gem to `Gemfile`:
++
+[source,ruby]
+gem 'releasehx', path: '../releasehx'
+
+. Draft RHYML draft file from the online GitHub Issues for the given version:
++
+[.prompt,subs=+attributes]
+ ./releasehx-install.sh && bundle exec rhx {this_prod_vrsn} --yaml docs/releasehx/release-{this_prod_vrsn}.yml --config docs/releasehx/config.yml
++
+The `releasehx-install.sh` ensures ReleaseHx is up to date.
+
+. Manually edit the RHYML draft file.
+
+. Generate the release history as Markdown.
++
+[.prompt,subs=+attributes]
+ bundle exec rhx docs/releasehx/release-{this_prod_vrsn}.yml --md docs/releasehx/{this_prod_vrsn}.md --config docs/releasehx/config.yml
+
+. Copy and paste the contents of `docs/releasehx/{this_prod_vrsn}.md` into the GitHub release form at https://github.com/DocOps/issuer/releases/new.
+
 [[contributing]]
 === Contributing
 

data/examples/basic-example.yml

@@ -5,6 +5,7 @@ $meta:
     vrsn: 1.0.0
     user: project-manager
     tags: [enhancement]
+    type: Task
 
 issues:
   - summ: Add user authentication
@@ -15,6 +16,7 @@ issues:
       - Password hashing
       - Session management
       - Two-factor authentication support
+    type: Feature
     tags: [security, authentication]
     user: backend-dev
 
@@ -22,6 +24,7 @@ issues:
     body: |
       The current layout breaks on mobile devices.
       Need to ensure proper responsive behavior.
+    type: Bug
     tags: [bug, ui, mobile]
     user: frontend-dev
 

data/examples/new-project-issues.yml

@@ -6,6 +6,7 @@ $meta:
   defaults:
     vrsn: 0.1.0
     user: project-lead
+    type: Task
     tags: [project-setup, +new-project]
     stub: true
     head: |
@@ -34,6 +35,7 @@ issues:
       - Set up .gitignore file
       - Add initial directory structure
       - Configure repository settings and permissions
+    type: Epic
     tags: [infrastructure, repository]
     user: devops-lead
 
@@ -110,6 +112,7 @@ issues:
       - Static code analysis for security issues
       - Secrets management setup
       - Security policy documentation
+    type: Story
     tags: [security, compliance, +critical]
     user: security-team
 

data/examples/tag-removal-example.yml

@@ -0,0 +1,41 @@
+# Tag Removal Example - Issue #4 Implementation
+# 
+# This example demonstrates the new tag removal functionality where
+# tags prefixed with '-' are removed from the default/appended tags list.
+
+$meta:
+  proj: myorg/myrepo
+  defaults:
+    tags: [+posted-by-issuer, needs:label, +needs:docs]
+
+issues:
+  - summ: Fix misstatement in the README
+    body: |
+      Correct that really bad typo on the first paragraph.
+      No docs needed for this change since it's a docs change.
+    tags: [documentation, -needs:docs]
+  
+  - summ: Issue that will be fixed immediately
+    tags: 
+      - '-needs:label'
+
+  - summ: Complex issue with multiple tag operations
+    body: |
+      This issue demonstrates multiple tag operations:
+      - Adds bug and enhancement tags
+      - Removes the default needs:label tag
+      - Removes the appended needs:docs tag
+      - Keeps the posted-by-issuer tag (append)
+    tags: [bug, enhancement, -needs:label, -needs:docs]
+    
+  - summ: Issue with no custom tags
+    body: |
+      This issue has no custom tags, so it gets all default tags
+      including both regular defaults and append tags.
+    # No tags specified - gets all defaults
+    
+  - summ: Issue that only removes tags
+    body: |
+      This issue only removes tags, so it gets default tags
+      minus the removed ones.
+    tags: [-needs:docs]

data/examples/validation-test.yml

@@ -1,8 +1,10 @@
 issues:
   - summ: Test milestone validation
     desc: This issue has a milestone that probably doesn't exist
+    type: Bug
     vrsn: test-milestone-v1.0
     tags: [test-label-1, existing-bug]
   - summ: Test label validation  
     desc: This issue has labels that probably don't exist
+    type: Task
     tags: [test-label-2, test-label-3, enhancement]

data/issuer.gemspec

@@ -15,6 +15,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/DocOps/issuer"
   spec.metadata["changelog_uri"] = "https://github.com/DocOps/issuer/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://gemdocs.org/gems/issuer/#{Issuer::VERSION}"
 
   # Specify which files should be added to the gem when it is released.
   spec.files = Dir['lib/**/*.rb'] +