docs: add comprehensive PUBLISH.md documentation

[pyramation]

docs: add comprehensive PUBLISH.md documentation

Summary

This PR adds comprehensive documentation for the multi-version publishing workflow in the pgsql-parser monorepo. The documentation covers the complex publishing system that supports PostgreSQL versions 13-17, each with their own npm tags (pg13, pg14, pg15, pg16, pg17) and version-specific packages.

Key areas documented:

• Prerequisites: yarn && yarn build workflow
• Multi-version system overview using config/versions.json
• Parser package publishing using prepare-versions.ts script
• Deparser package publishing using template-based generate-version-packages.ts
• Complete step-by-step publishing procedures for both individual and Lerna workflows
• Troubleshooting section for common issues

The documentation is designed to provide a clear, actionable path for publishing packages in this complex multi-version environment.

Review & Testing Checklist for Human

• Test the documented publishing workflow end-to-end - Follow the complete publishing procedure on a test branch to verify all commands work as documented
• Verify file paths and script references - Ensure all referenced files (config/versions.json, scripts/prepare-versions.ts, etc.) exist at the documented locations
• Check command accuracy - Validate that npm scripts, shell commands, and lerna commands are correct and include all necessary flags
• Review completeness - Confirm no critical steps or important context is missing from the publishing workflows

Recommended test plan: Create a test branch, follow the "Complete Publishing Procedure" section step-by-step, and verify that packages can be successfully prepared and built (stop before actual npm publish to avoid accidental releases).

---

Diagram

%%{ init : { "theme" : "default" }}%%
flowchart TD
    ConfigVersions["config/versions.json<br/>(version mappings)"]:::context
    PublishMD["PUBLISH.md<br/>(new documentation)"]:::major-edit
    
    ParserScripts["packages/parser/scripts/<br/>prepare-versions.ts"]:::context
    DeparserScripts["packages/deparser/scripts/<br/>generate-version-packages.ts"]:::context
    DeparserConfig["packages/deparser/config/<br/>deparser-versions.json"]:::context
    
    LernaConfig["lerna.json<br/>(monorepo config)"]:::context
    RootPackage["package.json<br/>(root scripts)"]:::context
    
    ConfigVersions --> PublishMD
    ParserScripts --> PublishMD
    DeparserScripts --> PublishMD
    DeparserConfig --> PublishMD
    LernaConfig --> PublishMD
    RootPackage --> PublishMD
    
    PublishMD -.-> Users["Developers following<br/>publishing procedures"]
    
    subgraph Legend
        L1["Major Edit"]:::major-edit
        L2["Minor Edit"]:::minor-edit  
        L3["Context/No Edit"]:::context
    end

    
    classDef major-edit fill:#90EE90
    classDef minor-edit fill:#87CEEB
    classDef context fill:#FFFFFF

Loading

Notes

This is a documentation-only PR that creates a single new file. The main risk is accuracy - while I thoroughly examined the existing scripts and configuration files to understand the publishing workflow, I did not execute the actual publishing process to verify the documented procedures work end-to-end. Human testing of the documented workflow is essential to catch any inaccuracies or missing steps.

Link to Devin run: https://app.devin.ai/sessions/6bb71417e0104b5189ec3125c0f503a9
Requested by: Dan Lynch (@pyramation)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring