Skip to content

Latest commit

 

History

History
172 lines (134 loc) · 4.64 KB

PUBLISHING.md

File metadata and controls

172 lines (134 loc) · 4.64 KB

DevPages Publishing Workflow

This document explains how to publish updates to the unified devpages package using the Option C: Subtree/Separate Repo approach.

🏗️ Repository Structure

study-groups/devops/
├── devpages/
│   ├── packages/                    # 🚧 Development Area
│   │   ├── devpages-statekit/      # Individual module development
│   │   ├── devpages-debug/         # Individual module development  
│   │   └── [future-modules]/
│   │
│   └── published/                   # 📦 Publishing Area
│       └── devpages/               # Unified package for publishing
│           ├── src/
│           │   ├── index.js        # Main entry point
│           │   ├── statekit/       # Compiled from packages/devpages-statekit
│           │   └── debug/          # Compiled from packages/devpages-debug
│           ├── dist/              # Built distributions
│           └── package.json       # name: "devpages"

study-groups/devpages-package.git    # 🎯 Dedicated Package Repo (this repo)

🔄 Development Workflow

1. Develop Individual Modules

# Work on statekit
cd devops/devpages/packages/devpages-statekit/
# make changes, test, commit to devops repo

# Work on debug tools  
cd devops/devpages/packages/devpages-debug/
# make changes, test, commit to devops repo

2. Update Unified Package

# Navigate to publishing area
cd devops/devpages/published/devpages/

# Copy updated modules from packages/
cp -r ../../packages/devpages-statekit/src/* src/statekit/
cp -r ../../packages/devpages-debug/src/* src/debug/

# Build unified package
npm run build

# Test the unified package
npm test  # if you have tests

3. Publish to Package Repository

# Commit changes in devops repo
git add .
git commit -m "Update devpages package v1.0.x"

# Push to dedicated package repo using subtree
git subtree push --prefix=devpages/published/devpages package-repo main

# Tag the release
git tag v1.0.x
git push package-repo v1.0.x

📦 Publishing Commands

Initial Setup (One Time)

# In your devops repository
cd devops/

# Add the package repo as a remote
git remote add package-repo git@github.com:study-groups/devpages-package.git

# Initial push of the unified package
git subtree push --prefix=devpages/published/devpages package-repo main

Regular Publishing

# After making changes to devpages/published/devpages/
git add devpages/published/devpages/
git commit -m "feat: Update devpages package v1.0.x

- Updated statekit with new features
- Enhanced debug panel performance  
- Fixed TypeScript definitions"

# Push to package repo
git subtree push --prefix=devpages/published/devpages package-repo main

# Create release tag
git tag v1.0.x -m "Release v1.0.x"
git push package-repo v1.0.x

🎯 User Installation

Users can now install your package cleanly:

# Latest version
npm install git+https://github.com/study-groups/devpages-package.git

# Specific version
npm install git+https://github.com/study-groups/devpages-package.git#v1.0.1

# In package.json
{
  "dependencies": {
    "devpages": "git+https://github.com/study-groups/devpages-package.git#v1.0.1"
  }
}

🚀 Automated Publishing (Optional)

You can set up GitHub Actions to automate this:

# .github/workflows/publish-package.yml
name: Publish DevPages Package

on:
  push:
    paths:
      - 'devpages/published/devpages/**'
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
          
      - name: Push to package repo
        run: |
          git remote add package-repo git@github.com:study-groups/devpages-package.git
          git subtree push --prefix=devpages/published/devpages package-repo main

📝 Version Management

Semantic Versioning

  • Major (1.0.0 → 2.0.0): Breaking changes
  • Minor (1.0.0 → 1.1.0): New features
  • Patch (1.0.0 → 1.0.1): Bug fixes

Release Process

  1. Update version in package.json
  2. Update CHANGELOG.md
  3. Commit and push to devops
  4. Subtree push to package repo
  5. Create git tag
  6. Create GitHub release (optional)

🔍 Benefits of This Approach

  • ✅ Clean user experience: Simple GitHub installation
  • ✅ Smaller downloads: Only package files, not entire devops repo
  • ✅ Focused documentation: Package-specific README
  • ✅ Separate issue tracking: Package issues separate from devops
  • ✅ Better versioning: Clean release history
  • ✅ Development flexibility: Work on modules independently