GitHub Integration Guide

The ISDL VS Code extension provides comprehensive GitHub integration, allowing you to publish and share your tabletop RPG systems directly from the editor. All you need is a Github account! This guide covers authentication, repository management, and publishing workflows.

Overview

GitHub integration enables you to:

• 🔐 Authenticate securely with GitHub using VS Code's built-in OAuth
• 📦 Publish systems as releases with automatic versioning and release notes
• 🔄 Update systems with intelligent change detection
• 📋 Share ISDL files via GitHub Gists

Getting Started

1. Authentication Setup

The extension uses VS Code's secure GitHub authentication system.

To connect your GitHub account:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run ISDL - GitHub: Connect to GitHub
3. Click "Connect to GitHub" in the setup wizard
4. VS Code will open GitHub's OAuth page in your browser
5. Authorize the ISDL extension with the required permissions:
   • repo - Repository access for publishing systems
   • user:email - Read your email address
   • actions:write - Create GitHub Actions workflows
   • contents:write - Write to repository contents
   • workflow - Manage GitHub Actions workflows
   • gist - Create and manage Gists for sharing ISDL files

Visual confirmation:

• You'll see "Successfully connected to GitHub as [username]"
• The GitHub view in the ISDL sidebar will show your connected status
• Your GitHub avatar will appear in the activity bar

There is also a sidebar UI for this workflow.

2. Repository Setup

After authentication, you can either create a new repository or connect to an existing one.

Creating a new repository:

1. In the ISDL sidebar, click "Create Repository"
2. Enter repository details:
   • Name: System identifier (e.g., "my-fantasy-system")
   • Description: Brief description of your system
   • Visibility: Public (required for others to install) or Private (for in-progress systems you're not ready to share)
   • License: Choose from MIT, LGPL v3.0, or Unlicense
3. The extension will:
   • Create the repository on GitHub
   • Initialize it with the correct branch structure
   • Add appropriate topics (foundry-vtt, tabletop-rpg, isdl)
   • Set up GitHub Actions workflow for automated releases

Connecting to existing repository:

1. Click "Select Repository" in the ISDL sidebar
2. Choose from your existing repositories
3. The extension will automatically detect if it's an ISDL-compatible repository

Core Features

System Publishing

Publishing creates a GitHub release with all your system files and provides an installation URL for Foundry VTT.

To publish your system:

1. Ensure your ISDL file is saved and your system is generated
2. In the ISDL sidebar, click "Publish System" or use Ctrl+Shift+P → ISDL - GitHub: Publish System
3. Select which ISDL file to publish (if you have multiple)
4. The extension will:
   • Analyze your ISDL file for changes
   • Collect all generated system files
   • Upload files to your repository
   • Create a GitHub release with semantic versioning
   • Generate comprehensive release notes
   • Provide installation instructions

What gets published:

• All generated Foundry VTT system files (system.json, data models, sheets, etc.)
• Your source ISDL file
• GitHub Actions workflow for release automation
• Comprehensive README with installation instructions

System Updates

For iterative development, use the update feature to push changes without creating a new release.

To update your system:

1. Make changes to your ISDL file and regenerate
2. Click "Update Files" in the sidebar or use Ctrl+Shift+P → ISDL - GitHub: Update Files
3. The extension will:
   • Compare file contents with the repository
   • Only upload files that have actually changed
   • Create a commit with a descriptive message
   • Skip release creation

Intelligent change detection:

• Uses SHA-1 hashing to detect actual content changes
• Skips unchanged files to optimize upload time
• Shows summary of changed files vs total files
• Preserves existing files not part of the system

Semantic Versioning

The extension automatically determines version bumps based on ISDL changes. This is helpful for modules that are written against your system to declare what versions of your system they are compatible with - if they rely on "system.fight" existing, a breaking change that removes it will impact their module.

• Major version (1.0.0 → 2.0.0): Removed or renamed fields/actions (breaking changes)
• Minor version (1.0.0 → 1.1.0): Added fields, actions, or system configuration changes
• Patch version (1.0.0 → 1.0.1): Implementation updates, bug fixes, styling changes

Version determination process:

1. Compares current ISDL with the last published version
2. Analyzes added, removed, and modified elements
3. Determines appropriate semantic version bump
4. Generates detailed changelog from detected changes

Automated Release Notes and Changelogs

The extension provides intelligent changelog generation by analyzing changes to your ISDL files between versions. This feature tracks the evolution of your system over time and helps users understand what changed in each release.

Changelog Features:

• Semantic Analysis - Understands field additions, removals, and modifications
• Breaking Change Detection - Identifies changes that might affect existing characters
• Foundry Compatibility Tracking - Notes when Foundry VTT version support changes
• System Metadata Changes - Tracks updates to system name, description, author, etc.

Release Note Categories:

• 🚨 Breaking Changes - Removed or renamed fields that might break existing data
• ✨ New Features - Added fields, actions, documents, or capabilities
• 🔧 Improvements - Modified existing features or enhanced functionality
• 🐛 Bug Fixes - Implementation fixes and corrections
• 📝 Documentation - Updated descriptions, labels, or help text
• 🎨 Style Updates - Visual improvements, icons, colors, layouts

Each release includes comprehensive, auto-generated release notes:

## My Fantasy System Release

📅 **Release Date:** 2025-01-15
🎲 **Foundry VTT Compatibility:** v12 - v13

### 📦 Installation

**Manifest URL:**

https://github.com/username/my-fantasy-system/releases/download/v1.2.0/system.json

### 🚀 What's New

#### ✨ New Features
- 📝 Added field 'Mana' to PC
- ⚡ Added action 'Cast Spell' to PC - Attributes

#### 🔧 Improvements  
- 📝 Modified field 'Health' in PC - enhanced calculation
- 🔧 Updated system description: Enhanced magic system

### 📖 Documentation
[Links to repository, issues, discussions]

### ⚡ Quick Start
[Step-by-step installation instructions]

Version History and Tracking

The extension maintains detailed version history to enable intelligent change detection and rollback capabilities.

Version Tracking Features:

• ISDL File Versioning - Snapshots of your ISDL file for each release
• Generated Content Tracking - Monitors changes to generated system files
• Dependency Analysis - Tracks field relationships and computed dependencies
• Migration Assistance - Helps identify potential data migration needs

Accessing Version History:

1. Via GitHub Releases - Each release contains the ISDL file used to generate it
2. Through VS Code - Extension tracks local ISDL file changes
3. Commit History - Git commits show progression of your system development
4. Changelog Files - Automatically generated CHANGELOG.md for each repository

Rollback and Recovery:

• Download previous ISDL versions from GitHub releases
• Compare current vs previous versions to understand changes
• Use Git history to revert to previous states
• Extension provides warnings about potentially breaking changes

Gist Integration

Share individual ISDL files quickly using GitHub Gists - perfect for sharing examples, getting feedback, or collaborating.

Creating a Gist:

1. Open your ISDL file in VS Code
2. Use Ctrl+Shift+P → ISDL - GitHub: Create Gist
3. Choose:
   • Description: Brief description of your system
   • Visibility: Public (searchable) or Secret (link-only access)
4. Get a shareable URL immediately

Managing Gists:

• Update: Sync changes to existing Gists
• Download: Pull ISDL files from Gists into your workspace
• Browse: View all your ISDL-related Gists
• Delete: Remove Gists you no longer need

Gist features:

• Automatic ISDL syntax highlighting on GitHub
• Version history tracking
• Comments and discussion
• Easy forking for collaboration
• Direct link sharing

Advanced Features

GitHub Actions Workflow

The extension automatically creates a GitHub Actions workflow that:

• Generates system archives for distribution
• Manages release assets

Workflow location: .github/workflows/main.yml

Repository Management

Repository topics: Automatically adds relevant topics:

• foundry-vtt - For Foundry VTT systems
• tabletop-rpg - For tabletop gaming
• isdl - For ISDL-generated systems

Branch management:

• Uses configurable default branch (main by default)
• Preserves existing files (LICENSE, README, etc.)
• Handles branch initialization for empty repositories
• Supports existing repository structures

Configuration Options

Access advanced settings through VS Code preferences (Ctrl+, → search "ISDL GitHub"):

{
  "fsdl.github.defaultBranch": "main",
  "fsdl.github.includeDocumentation": true,
  "fsdl.github.includeBuildScripts": true,
  "fsdl.github.repositoryVisibility": "public",
  "fsdl.github.licenseTemplate": "mit",
  "fsdl.github.autoPublish": false,
  "fsdl.github.tagReleases": true,
  "fsdl.github.generateChangelog": true
}

Key settings:

• defaultBranch: Main branch name (main/master/develop)
• includeDocumentation: Auto-generate README files
• includeBuildScripts: Include GitHub Actions workflows
• repositoryVisibility: Default visibility for new repositories
• licenseTemplate: Default license for new repositories
• autoPublish: Automatically publish on system generation
• tagReleases: Create Git tags for releases
• generateChangelog: Generate CHANGELOG.md files

Troubleshooting

Authentication Issues

"Failed to authenticate with GitHub"

• Ensure you're connected to the internet
• Try signing out and reconnecting
• Check if GitHub is experiencing issues
• Verify VS Code has necessary permissions

"Insufficient permissions"

• The extension requires specific scopes - reconnect to grant them
• Private repositories need repo scope
• Public repositories need public_repo scope

Publishing Issues

"No system files found"

• Generate your system first using ISDL: Generate
• Check that the generation completed successfully
• Verify files exist in your configured output directory

"Failed to create release"

• Check if a release with the same version already exists
• Verify repository write permissions
• Ensure the repository isn't archived or read-only

"No changes detected"

• Your files are already up to date in the repository
• Try regenerating your system to force changes
• Check if you're working in the correct output directory

Network Issues

"Request timeout" or "Connection failed"

• Check your internet connection
• Verify GitHub is accessible
• Try again after a few minutes
• Check if you're behind a corporate firewall

Version Issues

"Invalid version number"

• The extension auto-generates valid semantic versions
• If custom versioning fails, it falls back to incremental numbering
• Manual version tags should follow semantic versioning (X.Y.Z)

Best Practices

Repository Organization

• Use descriptive repository names matching your system ID
• Include comprehensive descriptions
• Add relevant topics for discoverability
• Keep your ISDL file in the repository root

Version Management

• Let the extension handle semantic versioning automatically
• Use meaningful commit messages for better release notes
• Test your system before publishing releases
• Use updates for development iterations, releases for stable versions

Collaboration

• Use Gists for sharing work-in-progress systems
• Enable discussions on your repository for community feedback
• Use issues to track bugs and feature requests
• Consider using pull requests for collaborative development

Documentation

• Enable automatic documentation generation
• Include usage examples in your repository
• Link to Foundry VTT installation guides
• Provide system-specific setup instructions

Security Considerations

• Permissions: The extension only requests necessary GitHub scopes
• Authentication: Uses VS Code's secure token storage
• Privacy: ISDL files in public repositories are publicly visible
• Access: Repository permissions follow your GitHub settings
• Tokens: Access tokens are managed by VS Code, not stored by the extension

Getting Help

Extension Issues:

• Check the VS Code Output panel → "ISDL"
• Look for error messages in the Developer Console
• Report issues on the ISDL GitHub repository

GitHub API Issues:

• Check GitHub Status for service issues
• Verify your GitHub account isn't rate-limited
• Review GitHub's API documentation for limits

General Support:

• Visit the ISDL Wiki for comprehensive guides
• Join community discussions on the repository
• Check existing issues for similar problems