feat(docs): update tutorial for building ytx .NET global tool

📝 Revised the tutorial to enhance clarity and provide updated
information on building the `ytx` tool.
📁 Modified: _posts/2025-08-31-building-ytx-a-youtube-transcript-extractor-as-a-dotnet-global-tool.md
🔧 Improved descriptions and summaries to better reflect the
extraction of YouTube transcripts and metadata as JSON
⚙️ Expanded CI/CD pipeline details with GitHub Actions for
production readiness and best practices
📦 Included insights on using AI tools to accelerate the
development process and emphasized design-first and documentation-driven
approaches

Author: solrevdev

_posts/2025-08-31-building-ytx-a-youtube-transcript-extractor-as-a-dotnet-global-tool.md

@@ -1,8 +1,8 @@
 ---
 layout: post
 title: Building ytx - A YouTube Transcript Extractor as a .NET Global Tool
-description: How to build a .NET Global Tool that extracts YouTube video metadata and transcripts as structured JSON, from concept to NuGet publication
-summary: A tutorial on creating ytx, a .NET global tool that extracts YouTube video titles, descriptions, and transcripts as JSON using YoutubeExplode and automated CI/CD.
+description: Build a .NET Global Tool to extract YouTube transcripts and metadata as JSON. Learn YoutubeExplode, CLI argument parsing, NuGet packaging, and GitHub Actions automation from concept to publication.
+summary: Complete tutorial on creating ytx, a .NET global tool for extracting YouTube video titles, descriptions, and transcripts as JSON. Covers YoutubeExplode library, caption selection logic, JSON serialization, NuGet packaging, and automated CI/CD with GitHub Actions.
 cover_image: /images/ytx-dotnet-tool-cover.svg
 tags:
 - dotnet-global-tools
@@ -19,7 +19,7 @@ tags:
 
 Sometimes you need to extract structured data from YouTube videos for analysis, documentation, or automation. While there are various web-based solutions, having a command-line tool that outputs clean JSON makes integration with scripts and pipelines much easier.
 
-I built `ytx` - a .NET Global Tool that extracts YouTube video metadata and transcripts as structured JSON. The tool takes a YouTube URL and returns the video title, description, and full transcript with timestamps in both raw text and markdown formats.
+I built **ytx** - a .NET Global Tool that extracts YouTube video metadata and transcripts as structured JSON. The tool takes a YouTube URL and returns the video title, description, and full transcript with timestamps in both raw text and markdown formats. This post walks you through building your own .NET global tool from scratch, covering architecture design, caption handling, JSON serialization, NuGet packaging, and setting up automated CI/CD with GitHub Actions.
 
 **The Problem** 🎯
 
@@ -294,66 +294,199 @@ The tool produces clean, structured JSON:
 
 The markdown transcript format makes it easy to create documentation with clickable timestamps that jump directly to specific moments in the video.
 
-**Automated CI/CD Pipeline** 🤖
+**Production-Ready CI/CD Pipeline with GitHub Actions** 🤖
 
-To streamline releases, I set up GitHub Actions to automatically:
-- Build and test the project
-- Increment version numbers
-- Publish to NuGet
-- Create GitHub releases
+To streamline releases and reduce manual work, I set up GitHub Actions to automatically handle the entire release pipeline. Unlike simple workflows, this production pipeline:
+- Runs on every push to `master` (only when source files change, avoiding redundant builds)
+- Allows manual triggers with version bump selection (patch, minor, or major)
+- Automatically increments semantic versions in your `.csproj` file
+- Commits version changes back to the repository with git tags
+- Builds and publishes to NuGet with proper error handling
+- Creates GitHub releases with auto-generated release notes
+- Supports multiple .NET versions (8.x and 9.x) for maximum compatibility
 
-The workflow file (`.github/workflows/publish.yml`) handles version bumping:
+The complete workflow file (`.github/workflows/publish.yml`) handles all of this:
 
 ```yaml
 name: Publish NuGet (ytx)
 
 on:
-  push:
-    branches: [ master ]
   workflow_dispatch:
     inputs:
-      version_bump:
-        description: 'Version bump type'
+      bump:
+        description: 'Version bump type (major|minor|patch)'
         required: true
         default: 'patch'
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
+  push:
+    branches: [ "master" ]
+    paths:
+      - 'src/Ytx/**'
+      - '.github/workflows/publish.yml'
+
+permissions:
+  contents: write
+  packages: read
+
+env:
+  PROJECT_DIR: src/Ytx
+  CSPROJ: src/Ytx/Ytx.csproj
+  NUPKG_DIR: nupkg
+  NUGET_SOURCE: https://api.nuget.org/v3/index.json
 
 jobs:
-  publish:
+  build-pack-publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      
+      - name: Checkout
+        uses: actions/checkout@v4
+
       - name: Setup .NET
         uses: actions/setup-dotnet@v4
         with:
           dotnet-version: |
-            8.0.x
-            9.0.x
+            9.x
+            8.x
 
-      - name: Bump version
-        run: |
-          # Script to increment version in .csproj
-          VERSION_TYPE="{% raw %}${{ github.event.inputs.version_bump || 'patch' }}{% endraw %}"
-          ./scripts/bump-version.sh "$VERSION_TYPE"
+      - name: Restore
+        run: dotnet restore $PROJECT_DIR
 
-      - name: Build and Pack
+      - name: Determine and bump version
+        id: bump
+        shell: bash
         run: |
-          dotnet restore src/Ytx
-          dotnet build src/Ytx -c Release
-          dotnet pack src/Ytx -c Release
+          set -euo pipefail
+          CURR=$(grep -oPm1 '(?<=<Version>)[^<]+' "$CSPROJ")
+          echo "Current version: $CURR"
+          IFS='.' read -r MAJ MIN PAT <<< "$CURR"
+          BUMP="${{ github.event.inputs.bump || 'patch' }}"
+          case "$BUMP" in
+            major) MAJ=$((MAJ+1)); MIN=0; PAT=0 ;;
+            minor) MIN=$((MIN+1)); PAT=0 ;;
+            patch|*) PAT=$((PAT+1)) ;;
+          esac
+          NEW="$MAJ.$MIN.$PAT"
+          echo "New version: $NEW"
+          sed -i "s|<Version>$CURR</Version>|<Version>$NEW</Version>|" "$CSPROJ"
+          echo "version=$NEW" >> "$GITHUB_OUTPUT"
+
+      - name: Commit version bump
+        if: ${{ github.ref == 'refs/heads/master' }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add ${{ env.CSPROJ }}
+          git commit -m "chore: bump version to ${{ steps.bump.outputs.version }}"
+          git tag "v${{ steps.bump.outputs.version }}"
+          git push --follow-tags
+
+      - name: Build
+        run: dotnet build $PROJECT_DIR -c Release --no-restore
+
+      - name: Pack
+        run: dotnet pack $PROJECT_DIR -c Release --no-build
 
       - name: Publish to NuGet
+        env:
+          NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
         run: |
-          dotnet nuget push nupkg/*.nupkg \
-            --api-key {% raw %}${{ secrets.NUGET_API_KEY }}{% endraw %} \
-            --source https://api.nuget.org/v3/index.json
+          dotnet nuget push $NUPKG_DIR/*.nupkg \
+            --api-key "$NUGET_API_KEY" \
+            --source "$NUGET_SOURCE" \
+            --skip-duplicate
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.bump.outputs.version }}
+          name: ytx v${{ steps.bump.outputs.version }}
+          generate_release_notes: true
 ```
 
+**Understanding the Workflow Architecture** 🏗️
+
+This workflow implements several production best practices that help .NET developers distribute global tools effectively:
+
+**Environment Variables for DRY Principle:**
+The `env:` block defines reusable values (`PROJECT_DIR`, `CSPROJ`, `NUPKG_DIR`, `NUGET_SOURCE`) referenced throughout the workflow. This approach keeps configuration centralized—change a directory path once, and it updates everywhere. This is crucial when managing complex multi-project solutions or adjusting package output locations.
+
+**Permissions Block:**
+The `permissions:` section restricts the workflow to only what it needs:
+- `contents: write` — Required to create commits, tags, and push back to the repository
+- `packages: read` — Required for accessing NuGet package data
+
+This follows the principle of least privilege, improving security by preventing the workflow from performing unauthorized actions.
+
+**Smart Trigger Configuration:**
+```yaml
+on:
+  push:
+    branches: [ "master" ]
+    paths:
+      - 'src/Ytx/**'
+      - '.github/workflows/publish.yml'
+```
+
+The `paths:` filter prevents unnecessary builds when only documentation or other non-source files change. This saves CI/CD minutes and reduces feedback latency.
+
+**Semantic Version Bumping with bash:**
+The version bump step demonstrates how to parse and manipulate semantic versions programmatically:
+
+```bash
+IFS='.' read -r MAJ MIN PAT <<< "$CURR"  # Parse 1.0.2 into components
+case "$BUMP" in
+  major) MAJ=$((MAJ+1)); MIN=0; PAT=0 ;;  # 1.0.2 → 2.0.0
+  minor) MIN=$((MIN+1)); PAT=0 ;;         # 1.0.2 → 1.1.0
+  patch|*) PAT=$((PAT+1)) ;;             # 1.0.2 → 1.0.3
+esac
+```
+
+This approach ensures version consistency without manually editing `.csproj` files. The `echo "version=$NEW" >> "$GITHUB_OUTPUT"` sends the new version to subsequent steps—a key pattern in GitHub Actions workflows.
+
+**Git Automation for Reproducible Releases:**
+```bash
+git config user.name "github-actions[bot]"
+git add ${{ env.CSPROJ }}
+git commit -m "chore: bump version to ${{ steps.bump.outputs.version }}"
+git tag "v${{ steps.bump.outputs.version }}"
+git push --follow-tags
+```
+
+This creates an immutable audit trail. Every NuGet release corresponds to:
+1. A specific git commit (with the bumped version)
+2. A git tag (for easy checkout: `git checkout v1.0.3`)
+3. A GitHub release (with release notes)
+
+This traceability is essential for troubleshooting issues and understanding what code produced which package version.
+
+**Optimized Build Pipeline:**
+Notice the careful use of build flags:
+```bash
+dotnet restore $PROJECT_DIR              # Explicit restore
+dotnet build $PROJECT_DIR -c Release --no-restore    # Skip redundant restore
+dotnet pack $PROJECT_DIR -c Release --no-build       # Skip redundant build
+```
+
+The `--no-restore` and `--no-build` flags prevent repeating expensive operations. For .NET global tools especially, proper dependency isolation matters—you want to ensure your tool works across different .NET SDK versions, which is why this workflow tests against both 8.x and 9.x.
+
+**NuGet Publishing with Idempotency:**
+```bash
+dotnet nuget push $NUPKG_DIR/*.nupkg \
+  --skip-duplicate
+```
+
+The `--skip-duplicate` flag means you can safely re-run the workflow without errors if a version was already published. This is crucial for reliability—sometimes you need to retry a build due to temporary network issues or API timeouts.
+
+**Automated GitHub Releases:**
+```yaml
+- name: Create GitHub Release
+  uses: softprops/action-gh-release@v2
+  with:
+    tag_name: v${{ steps.bump.outputs.version }}
+    generate_release_notes: true
+```
+
+This automatically creates a GitHub release with auto-generated release notes based on commit messages since the last release. Users see a clear changelog without manual effort, and the release is properly associated with the NuGet package version.
+
 **Installation and Usage** 📦
 
 Once published to NuGet, users can install the tool globally:
@@ -386,15 +519,16 @@ The tool handles various error scenarios gracefully:
 
 This makes it suitable for use in scripts and automation pipelines.
 
-**Key Learnings** 💡
+**Key Learnings & Best Practices** 💡
 
-Building this tool taught me several valuable lessons:
+Building this .NET global tool taught me several valuable lessons applicable to any command-line tool project:
 
-1. **YoutubeExplode Evolution**: The library has improved significantly - version 6.5.4 resolved transcript extraction issues that existed in earlier versions
-2. **Global Tool Packaging**: The `PackageReadmeFile` and proper NuGet metadata are crucial for discoverability
-3. **Multi-targeting**: Supporting both .NET 8 and 9 ensures broader compatibility
-4. **JSON Input/Output**: Supporting both CLI args and stdin makes the tool more versatile for automation
-5. **Caption Prioritization**: Smart ordering logic for captions improves user experience significantly
+1. **YoutubeExplode Library Maturity**: Version 6.5.4 resolved transcript extraction issues that plagued earlier versions. Always verify library versions match your use case requirements.
+2. **.NET Global Tool Packaging**: The `PackAsTool` property, `ToolCommandName`, and `PackageReadmeFile` are crucial for NuGet discoverability. Missing these makes your tool harder to find.
+3. **Multi-targeting Strategy**: Supporting both .NET 8 and 9 simultaneously ensures broader compatibility across development environments and CI/CD pipelines.
+4. **Flexible Input/Output Design**: Supporting both command-line arguments and stdin (JSON) makes your tool more versatile for automation, scripting, and pipeline integration.
+5. **Intelligent Caption Selection**: Smart ordering logic (English preference → auto-generated fallback) dramatically improves user experience compared to simple "first available" approaches.
+6. **Semantic Versioning in CI/CD**: Automating patch/minor/major version bumps reduces manual work and ensures consistency across releases.
 
 **Future Enhancements** 🔮
 
@@ -406,36 +540,41 @@ Potential improvements for future versions:
 - Integration with subtitle file formats (SRT, VTT)
 - Translation support for non-English captions
 
-**Modern Development Velocity** ⚡
+**Development Velocity with Modern AI Tooling** ⚡
 
-What strikes me most about this project is the development speed enabled by modern AI tooling. From initial concept to published NuGet package took just a few hours - a timeframe that would have been unthinkable just a few years ago.
+What stands out about this project is the development speed enabled by modern AI assistance. From initial concept through architecture, implementation, testing, and NuGet publication took just a few hours - something that would have required days of work just five years ago.
 
-**The AI-Assisted Workflow** 🤖
+**The AI-Assisted Development Workflow** 🤖
 
-This project showcased the power of combining multiple AI tools:
+This .NET global tool project showcased the power of combining multiple AI tools effectively:
 
-- **Claude Code**: Handled the core architecture decisions, error handling patterns, and CI/CD pipeline setup. Particularly valuable for getting the .csproj packaging configuration right on the first try.
-- **GitHub Copilot**: Excelled at generating repetitive code patterns, JSON serialization boilerplate, and regex text normalization functions.
+- **Claude Code**: Handled core architecture decisions, .NET-specific patterns, error handling strategies, and GitHub Actions CI/CD pipeline configuration. Particularly valuable for getting the `.csproj` packaging configuration correct on the first attempt.
+- **GitHub Copilot**: Excelled at generating repetitive code patterns, JSON serialization boilerplate, regex text normalization functions, and test scaffold code.
 - **MCPs (Model Context Protocol)**: Provided seamless integration between different AI tools and development contexts, making the workflow feel natural rather than fragmented.
 
-**The Human-AI Partnership** 🤝
+**The Human-AI Partnership in Practice** 🤝
+
+The most interesting insight wasn't that AI wrote the code, but how it transformed the development process itself:
 
-The most interesting aspect wasn't that AI wrote the code, but how it changed the development process itself:
+1. **Design-First Development**: Instead of iterating through implementation details, focus shifted to user experience and clean data flow architecture.
+2. **Documentation-Driven Development**: Writing this technical blog post in parallel with coding helped clarify requirements and catch edge cases early.
+3. **Risk-Free Exploration**: AI assistance made it easy to try different architectural approaches without the usual "sunk cost" hesitation.
 
-1. **Design-First Thinking**: Instead of iterating through implementation details, I could focus on the user experience and data flow
-2. **Documentation-Driven Development**: Writing this blog post in parallel with coding helped clarify requirements and catch edge cases early
-3. **Confidence in Exploration**: Having AI assistance made it easy to try different approaches without the usual "sunk cost" feeling
+**What This Means for .NET Developers** 🚀
 
-**Looking Forward** 🔮
+This project represents a new normal in software development—where the bottleneck shifts from typing code to thinking through problems and user needs. The combination of AI coding assistants, intelligent build toolchains (GitHub Actions, NuGet), and human creativity is genuinely transformative.
 
-This project represents a new normal in software development - where the bottleneck shifts from typing code to thinking through problems and user needs. The combination of AI coding assistants, intelligent toolchains, and human creativity is genuinely transformative.
+For developers hesitant about AI tools: they're not replacing you; they're amplifying your ability to solve meaningful problems quickly. The future belongs to developers who can effectively collaborate with AI to build better software faster.
 
-For developers hesitant about AI tools: they're not replacing us, they're amplifying our ability to solve meaningful problems quickly. The future belongs to developers who can effectively collaborate with AI to build better software faster.
+**Get Started Building Your Own .NET Global Tool** 📦
 
-Ready to extract some YouTube transcripts? 🎬
+Ready to create your own command-line tool and publish it to NuGet? Install ytx to see a working example:
 
 ```powershell
 dotnet tool install -g solrevdev.ytx
+ytx "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
 ```
 
+Or [explore the source code on GitHub](https://github.com/solrevdev/solrevdev.ytx) to see the complete implementation.
+
 Success! 🎉