obsidian-prod-checklist

Obsidian Prod Checklist

Overview

Comprehensive pre-release checklist for submitting Obsidian plugins to the community plugin directory.

Prerequisites

• Completed plugin development
• Tested in multiple vaults
• GitHub repository ready

Community Plugin Requirements

Mandatory Items

• Plugin hosted on public GitHub repository
• Valid manifest.json with all required fields
• Valid versions.json tracking compatibility
• No console errors during normal operation
• Works on all platforms (desktop: Win/Mac/Linux, mobile: iOS/Android)

Instructions

Step 1: Validate manifest.json

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "1.0.0",
  "description": "A clear, concise description (max ~250 chars)",
  "author": "Your Name",
  "authorUrl": "https://github.com/username",
  "fundingUrl": "https://buymeacoffee.com/username",
  "isDesktopOnly": false
}

Validation Script:

#!/bin/bash
# validate-manifest.sh

MANIFEST="manifest.json"

# Check file exists
if [ ! -f "$MANIFEST" ]; then
  echo "ERROR: manifest.json not found"
  exit 1
fi

# Validate JSON syntax
if ! jq empty "$MANIFEST" 2>/dev/null; then
  echo "ERROR: Invalid JSON in manifest.json"
  exit 1
fi

# Check required fields
REQUIRED=("id" "name" "version" "minAppVersion" "description" "author")
for field in "${REQUIRED[@]}"; do
  if [ "$(jq -r ".$field" "$MANIFEST")" == "null" ]; then
    echo "ERROR: Missing required field: $field"
    exit 1
  fi
done

# Validate semver
VERSION=$(jq -r '.version' "$MANIFEST")
if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "ERROR: Version must be valid semver: $VERSION"
  exit 1
fi

echo "manifest.json validation passed"

Step 2: Validate versions.json

{
  "1.0.0": "1.0.0",
  "1.0.1": "1.0.0",
  "1.1.0": "1.2.0"
}

Format: "plugin-version": "minimum-obsidian-version"

# Validate versions.json
if [ ! -f "versions.json" ]; then
  echo "ERROR: versions.json not found"
  exit 1
fi

if ! jq empty "versions.json" 2>/dev/null; then
  echo "ERROR: Invalid JSON in versions.json"
  exit 1
fi

echo "versions.json validation passed"

Step 3: Code Quality Checks

#!/bin/bash
# quality-check.sh

echo "=== Code Quality Checks ==="

# TypeScript compilation
echo "Checking TypeScript..."
npm run build
if [ $? -ne 0 ]; then
  echo "ERROR: Build failed"
  exit 1
fi

# ESLint
echo "Running ESLint..."
npm run lint
if [ $? -ne 0 ]; then
  echo "WARNING: Linting issues found"
fi

# Check for console.log statements (should use proper logging)
echo "Checking for debug statements..."
CONSOLE_COUNT=$(grep -r "console.log" src/ --include="*.ts" | wc -l)
if [ "$CONSOLE_COUNT" -gt 0 ]; then
  echo "WARNING: Found $CONSOLE_COUNT console.log statements"
  grep -r "console.log" src/ --include="*.ts"
fi

# Check for hardcoded secrets patterns
echo "Checking for potential secrets..."
if grep -rE "(api[_-]?key|password|secret|token)\s*[:=]\s*['\"][^'\"]+['\"]" src/; then
  echo "ERROR: Potential hardcoded secrets found!"
  exit 1
fi

echo "Quality checks complete"

Step 4: Functionality Testing Checklist

## Manual Testing Checklist

### Installation
- [ ] Plugin installs correctly from .zip
- [ ] Plugin loads without errors
- [ ] Settings tab appears and functions
- [ ] All commands appear in command palette

### Core Features
- [ ] Primary feature works as expected
- [ ] Secondary features work correctly
- [ ] Settings persist after reload
- [ ] Plugin unloads cleanly

### Edge Cases
- [ ] Empty vault handling
- [ ] Large vault (1000+ files) performance
- [ ] Files with special characters in names
- [ ] Files with no frontmatter
- [ ] Files with malformed frontmatter

### Platform Testing
- [ ] Windows desktop
- [ ] macOS desktop
- [ ] Linux desktop
- [ ] iOS mobile
- [ ] Android mobile

### Compatibility
- [ ] Works with popular themes (minimal, default)
- [ ] No conflicts with common plugins
- [ ] Works in restricted mode (if applicable)

Step 5: Documentation Checklist

## README.md Requirements

### Required Sections
- [ ] Plugin name and brief description
- [ ] Installation instructions
- [ ] How to use (basic usage)
- [ ] Configuration/settings explanation
- [ ] Screenshots/demos (if visual)

### Recommended Sections
- [ ] Features list
- [ ] Changelog link
- [ ] Troubleshooting/FAQ
- [ ] Contributing guidelines
- [ ] License information

### Example Structure
```markdown
# Plugin Name

Brief description of what the plugin does.

## Features
- Feature 1
- Feature 2

## Installation
### From Obsidian
1. Open Settings > Community Plugins
2. Search for "Plugin Name"
3. Install and enable

### Manual
1. Download latest release
2. Extract to `.obsidian/plugins/`
3. Enable in settings

## Usage
Explain how to use the plugin.

## Settings
| Setting | Description | Default |
|---------|-------------|---------|
| Option 1 | What it does | value |

## Support
- [Report issues](link)
- [Discussions](link)

Step 6: GitHub Release Preparation

#!/bin/bash
# prepare-release.sh

VERSION=$(jq -r '.version' manifest.json)

# Create release directory
mkdir -p release

# Copy required files
cp main.js manifest.json styles.css release/ 2>/dev/null

# Create zip
cd release
zip "../my-plugin-${VERSION}.zip" *
cd ..

# Create release notes template
cat > "release-notes-${VERSION}.md" << EOF
## What's New in v${VERSION}

### Features
- New feature description

### Bug Fixes
- Fixed issue description

### Changes
- Changed behavior description

## Installation
Download \`my-plugin-${VERSION}.zip\` and extract to your vault's plugins folder.
EOF

echo "Release prepared: my-plugin-${VERSION}.zip"

Step 7: Submission Checklist

## Community Plugin Submission

### Pre-submission
- [ ] Tested on latest Obsidian version
- [ ] No beta API features used (or documented)
- [ ] Plugin ID is unique (check existing plugins)
- [ ] README clearly explains purpose

### Repository Requirements
- [ ] Public GitHub repository
- [ ] main.js in repository root
- [ ] manifest.json in repository root
- [ ] styles.css if using styles

### Submit PR to obsidian-releases
1. Fork https://github.com/obsidianmd/obsidian-releases
2. Add entry to community-plugins.json:
```json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "author": "Your Name",
  "description": "Brief description",
  "repo": "username/repo-name"
}

3. Create PR with description of plugin

After Submission

• Respond to reviewer feedback promptly
• Test any requested changes
• Update PR as needed

## Output
- Validated manifest.json and versions.json
- Code quality verified
- Functionality tested across platforms
- Documentation complete
- Release package prepared
- Submission checklist complete

## Error Handling
| Issue | Cause | Solution |
|-------|-------|----------|
| PR rejected | Missing fields | Check all manifest fields |
| Build fails in CI | Dependencies | Lock versions in package.json |
| Plugin not found | Wrong repo path | Verify repo matches submission |
| Mobile crash | Desktop-only API | Check `isDesktopOnly` flag |

## Examples

### Automated Release Script
```bash
#!/bin/bash
set -e

VERSION=$1
if [ -z "$VERSION" ]; then
  echo "Usage: ./release.sh 1.0.0"
  exit 1
fi

# Update version
npm version $VERSION --no-git-tag-version
node version-bump.mjs $VERSION

# Build
npm run build

# Test
npm test

# Create release
./prepare-release.sh

echo "Ready to create GitHub release for v$VERSION"

Resources

• Plugin Submission Guidelines
• Plugin Guidelines
• Obsidian Releases Repo

Next Steps

For version upgrades, see obsidian-upgrade-migration.