publishing-rules

# Publishing Rules Skill

<identity>
You are a coding standards expert specializing in publishing rules.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines for publishing packages and applications.

## NPM Package Publishing

### Package.json Configuration

Essential fields for npm packages:

```json
{
  "name": "@scope/package-name",
  "version": "1.0.0",
  "description": "Clear description of what the package does",
  "main": "dist/index.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist", "README.md", "LICENSE"],
  "scripts": {
    "build": "tsc && rollup -c",
    "test": "jest",
    "prepublishOnly": "npm run build && npm test"
  },
  "keywords": ["keyword1", "keyword2"],
  "author": "Your Name <email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/repo.git"
  },
  "bugs": {
    "url": "https://github.com/username/repo/issues"
  },
  "homepage": "https://github.com/username/repo#readme",
  "peerDependencies": {
    "react": "^18.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}
```

### Publishing Workflow

**Manual Publishing:**

```bash
# Login to npm
npm login

# Test package locally first
npm pack
npm install ./package-name-1.0.0.tgz

# Publish (scoped packages need --access public)
npm publish --access public
```

**Automated Publishing with CI/CD:**

```yaml
# GitHub Actions workflow
name: Publish to NPM

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci
      - run: npm test
      - run: npm run build

      # Verify version matches tag
      - name: Verify version
        run: |
          TAG="${GITHUB_REF#refs/tags/v}"
          VERSION=$(node -p "require('./package.json').version")
          if [ "$TAG" != "$VERSION" ]; then
            echo "Version mismatch"
            exit 1
          fi

      # Publish with provenance
      - run: npm publish --access public --provenance
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

**NPM Token Setup:**

- Use Granular Access Tokens (classic tokens are deprecated)
- Set appropriate scopes and expiration
- Store as `NPM_TOKEN` in GitHub Secrets

### Semantic Versioning

Follow semver (major.minor.patch):

```bash
# Bug fixes (1.0.0 -> 1.0.1)
npm version patch

# New features (1.0.0 -> 1.1.0)
npm version minor

# Breaking changes (1.0.0 -> 2.0.0)
npm version major

# Push tags
git push origin main --tags
```

### What to Exclude

Create `.npmignore`:

```
src/
tests/
*.test.js
.github/
.env
tsconfig.json
rollup.config.js
```

Or use `files` in package.json (recommended).

## Chrome Extension Publishing

### Manifest Validation

Ensure manifest.json meets store requirements:

```json
{
  "manifest_version": 3,
  "name": "Extension Name",
  "version": "1.0.0",
  "description": "Clear description under 132 characters",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "permissions": ["storage"],
  "host_permissions": ["https://*.example.com/*"],
  "action": {
    "default_popup": "popup.html"
  }
}
```

### Chrome Web Store Submission

**Preparation:**

1. Create high-quality icons (16x16, 48x48, 128x128)
2. Prepare promotional images (1280x800 or 640x400)
3. Write clear description and privacy policy
4. Test on multiple Chrome versions

**Submission Process:**

```bash
# Build production version
npm run build

# Create zip file
cd dist && zip -r ../extension.zip . && cd ..

# Upload to Chrome Web Store Developer Dashboard
# https://chrome.google.com/webstore/devconsole
```

**Publishing Checklist:**

- [ ] Valid manifest.json (no errors in chrome://extensions)
- [ ] All permissions justified in description
- [ ] Privacy policy URL (required if collecting data)
- [ ] Screenshots and promotional images
- [ ] Category selection
- [ ] Pricing and distribution settings

### Extension Update Process

```json
{
  "version": "1.0.1",
  "version_name": "1.0.1 - Bug fixes"
}
```

Chrome auto-updates extensions within 5 hours of publishing.

## App Store Submission (iOS)

### App Store Connect Preparation

**Required Assets:**

- App icons (1024x1024 for App Store)
- Screenshots for all device sizes
- Privacy policy URL
- Support URL

**Info.plist Requirements:**

```xml
<key>CFBundleShortVersionString</key>
<string>1.0.0</string>
<key>CFBundleVersion</key>
<string>1</string>
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <false/>
</dict>
```

**Submission via Xcode or Transporter:**

```bash
# Using xcrun altool (deprecated, use App Store Connect API)
xcrun altool --upload-app -f app.ipa -u username -p app-specific-password

# Modern approach: Use App Store Connect API with EAS or Fastlane
```

**Review Checklist:**

- [ ] No placeholder content
- [ ] All features functional
- [ ] No crashes or major bugs
- [ ] Privacy policy and permissions explained
- [ ] Age rating accurate
- [ ] Screenshots match current version

## Google Play Store Submission (Android)

### Play Console Requirements

**AAB (Android App Bundle) preferred over APK:**

```bash
# Build release AAB
./gradlew bundleRelease

# Sign with keystore
jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 \
  -keystore my-release-key.jks app-release.aab alias_name
```

**Store Listing Requirements:**

- App name (max 30 characters)
- Short description (max 80 characters)
- Full description (max 4000 characters)
- Screenshots (2-8 per device type)
- Feature graphic (1024x500)
- Privacy policy URL

**Release Tracks:**

- **Internal testing** - Up to 100 testers, instant updates
- **Closed testing** - Up to 100,000 testers, review required
- **Open testing** - Public, review required
- **Production** - Full release, review required

### Automated Play Store Publishing

```yaml
# Example with Expo EAS
eas submit --platform android --latest
```

## Release Notes Best Practices

### NPM Package Changelog

Follow Keep a Changelog format:

```markdown
# Changelog

## [1.2.0] - 2025-01-24

### Added

- New feature X for improved performance
- Support for TypeScript 5.0

### Changed

- Updated dependency Y to v3.0

### Fixed

- Bug causing crash on mobile devices

### Deprecated

- Function Z will be removed in v2.0

## [1.1.0] - 2025-01-10

...
```

### App Store Release Notes

**iOS (App Store Connect):**

```
What's New in Version 1.2.0

• Added dark mode support
• Improved performance on older devices
• Fixed crash when uploading photos
• Minor bug fixes and improvements
```

**Android (Play Console):**

```
Version 1.2.0 - January 24, 2025

New:
- Dark mode support
- Offline mode for saved content

Improvements:
- Faster app startup
- Better battery usage

Fixes:
- Resolved photo upload crash
```

## Version Management

### Consistent Versioning Across Platforms

**Package.json:**

```json
{
  "version": "1.2.0"
}
```

**Expo app.json:**

```json
{
  "expo": {
    "version": "1.2.0",
    "ios": {
      "buildNumber": "12"
    },
    "android": {
      "versionCode": 12
    }
  }
}
```

**Git Tags:**

```bash
git tag v1.2.0
git push origin v1.2.0
```

### Pre-release Versions

```bash
# NPM
npm publish --tag beta
npm install package@beta

# Expo
eas build --profile preview
```

## Quality Assurance Before Publishing

### Pre-publish Checklist

**NPM:**

- [ ] Tests pass (`npm test`)
- [ ] Build successful (`npm run build`)
- [ ] No security vulnerabilities (`npm audit`)
- [ ] README is up to date
- [ ] CHANGELOG updated
- [ ] Version bumped correctly
- [ ] Test local installation (`npm pack`)

**Chrome Extension:**

- [ ] No console errors
- [ ] Works in incognito mode
- [ ] All permissions necessary
- [ ] Privacy policy updated
- [ ] Screenshots current

**Mobile Apps:**

- [ ] Tested on multiple devices
- [ ] No crashes in production build
- [ ] Deep links working
- [ ] Push notifications functional
- [ ] Privacy policy compliant
- [ ] Age rating appropriate

</instructions>

<examples>
Example usage:
```
User: "Review this code for publishing rules compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.