Add stable releases and semantic versioning support

.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to release (e.g., v0.1.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Mark as pre-release'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Extract version from tag
+      id: version
+      run: |
+        if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+          TAG="${{ github.event.inputs.tag }}"
+        else
+          TAG="${GITHUB_REF#refs/tags/}"
+        fi
+        VERSION=${TAG#v}
+        echo "tag=$TAG" >> $GITHUB_OUTPUT
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "Tag: $TAG, Version: $VERSION"
+
+    - name: Update version in pyproject.toml
+      run: |
+        sed -i 's/version = "[^"]*"/version = "${{ steps.version.outputs.version }}"/' pyproject.toml
+        echo "Updated version to ${{ steps.version.outputs.version }}"
+        grep 'version =' pyproject.toml
+
+    - name: Generate changelog for this release
+      id: changelog
+      run: |
+        if [ ! -f CHANGELOG.md ]; then
+          echo "# Changelog" > CHANGELOG.md
+          echo "" >> CHANGELOG.md
+          echo "All notable changes to this project will be documented in this file." >> CHANGELOG.md
+          echo "" >> CHANGELOG.md
+          echo "The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)," >> CHANGELOG.md
+          echo "and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)." >> CHANGELOG.md
+          echo "" >> CHANGELOG.md
+        fi
+
+        # Extract release notes for this version
+        if grep -q "## \[${{ steps.version.outputs.version }}\]" CHANGELOG.md; then
+          awk '/## \[${{ steps.version.outputs.version }}\]/{flag=1; next} /## \[/{flag=0} flag' CHANGELOG.md > release_notes.md
+        else
+          echo "Release ${{ steps.version.outputs.tag }}" > release_notes.md
+          echo "" >> release_notes.md
+          echo "This release includes the latest improvements and bug fixes." >> release_notes.md
+        fi
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v1
+      with:
+        tag_name: ${{ steps.version.outputs.tag }}
+        name: Release ${{ steps.version.outputs.tag }}
+        body_path: release_notes.md
+        draft: false
+        prerelease: ${{ github.event.inputs.prerelease == 'true' }}
+        generate_release_notes: true
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Clean up
+      run: rm -f release_notes.md

CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Automated release workflow with GitHub Actions
+- Semantic versioning support
+- This CHANGELOG.md file
+
+### Changed
+- Repository now supports stable tags and releases
+
+## [0.1.0] - 2025-10-19
+
+### Added
+- NVSHMEM4Py Integration - replaced custom python bindings with official Python language binding for NVSHMEM
+- Cuda Graph support
+- Flexible transportation layers: NVLink, IBGDA, IBRC, EFA
+- Overlapping communication and computation
+- Comprehensive testing and benchmarking suite
+- C++ testing support with CMake
+- Multi-node testing and benchmarking capabilities
+
+### Changed
+- Migrated from static linking of host-side initialization (libnvshmem.a) to dynamic linking (libnvshmem_host.so)
+- Updated README.md with comprehensive installation and usage instructions
+- Improved project structure with proper Python packaging
+
+### Fixed
+- Fixed potential bugs in internode dispatch kernel (shared memory allocation and synchronization)
+- Fixed build linkage errors
+- Fixed NVSHMEM external variable instances issues
+- Memory leaks in Distributed::allToAllImpl (freed srcBuffer and dstBuffer)
+- Added device guard for kernel calls
+
+### Security
+- Proper linking of NVSHMEM to sublibraries as interface to prevent multiple instances
+
+---
+
+## Version History Overview
+
+This project follows [Semantic Versioning](https://semver.org/):
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for backwards-compatible functionality additions  
+- **PATCH** version for backwards-compatible bug fixes
+
+For consumers of pplx-kernels, you can now use version tags instead of pinning to specific SHAs:
+
+```bash
+# Install specific version
+pip install git+https://github.com/perplexityai/[email protected]
+
+# Or in requirements.txt
+git+https://github.com/perplexityai/[email protected]
+```

README.md

@@ -5,19 +5,50 @@ Features:
 * ✅ Cuda Graph support
 * ✅ Flexible transportation layers: NVLink, IBGDA, IBRC, EFA
 * ✅ Overlapping communication and computation
+* ✅ Stable releases with semantic versioning
 
 ## System Requirements
 
 To learn how to set up the system drivers and dependencies, refer to the [Install Driver and Dependencies](docs/install-driver-and-dependencies.md) guide.
 
 ## Installation
 
+### Using Stable Releases (Recommended)
+
+With stable releases, you can now pin to specific versions instead of commit SHAs:
+
+```bash
+# Install latest stable release
+pip install git+https://github.com/perplexityai/pplx-kernels.git
+
+# Install specific version
+pip install git+https://github.com/perplexityai/[email protected]
+```
+
+For use in `requirements.txt`:
+```
+# Pin to specific stable version
+git+https://github.com/perplexityai/[email protected]
+
+# Or use latest release
+git+https://github.com/perplexityai/pplx-kernels.git
+```
+
+### Development Installation
+
+For development or building from source:
+
 ```bash
+git clone https://github.com/perplexityai/pplx-kernels.git
 cd pplx-kernels
 TORCH_CUDA_ARCH_LIST=9.0a+PTX python3 setup.py bdist_wheel
 pip install dist/*.whl
 ```
 
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/). See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/RELEASE_PROCESS.md](docs/RELEASE_PROCESS.md) for release information.
+
 ## Single-node Testing and Benchmarking
 
 Test:
@@ -120,3 +151,7 @@ To run the all-to-all benchmarks on one node:
 ```bash
 NVSHMEM_REMOTE_TRANSPORT=none mpirun -np 4 ./all_to_all/bench_all_to_all
 ```
+
+## Contributing
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/RELEASE_PROCESS.md](docs/RELEASE_PROCESS.md) for information about releases.

docs/RELEASE_PROCESS.md

@@ -0,0 +1,171 @@
+# Release Process
+
+This document describes the release process for pplx-kernels, including how to create stable tags and releases.
+
+## Overview
+
+The pplx-kernels project follows [Semantic Versioning](https://semver.org/) and provides stable releases through Git tags and GitHub releases. This allows consumers to pin to specific versions instead of using commit SHAs.
+
+## Version Format
+
+Versions follow the format `vX.Y.Z` where:
+- `X` = Major version (breaking changes)
+- `Y` = Minor version (new features, backwards compatible)
+- `Z` = Patch version (bug fixes, backwards compatible)
+
+Examples: `v0.1.0`, `v1.0.0`, `v1.2.3`
+
+## Release Types
+
+### 1. Automated Release (Recommended)
+
+Use GitHub Actions workflow for consistent releases:
+
+1. Go to the [Actions tab](https://github.com/perplexityai/pplx-kernels/actions)
+2. Select "Release" workflow
+3. Click "Run workflow"
+4. Specify:
+   - Tag (e.g., `v0.2.0`)
+   - Whether it's a pre-release
+5. The workflow will:
+   - Update `pyproject.toml` version
+   - Create a Git tag
+   - Generate release notes
+   - Create GitHub release
+
+### 2. Manual Release
+
+For manual releases:
+
+```bash
+# 1. Update version in pyproject.toml
+sed -i 's/version = "[^"]*"/version = "0.2.0"/' pyproject.toml
+
+# 2. Update CHANGELOG.md
+# Add new version section with changes
+
+# 3. Commit changes
+git add pyproject.toml CHANGELOG.md
+git commit -m "Prepare release v0.2.0"
+
+# 4. Create and push tag
+git tag -a v0.2.0 -m "Release v0.2.0"
+git push origin v0.2.0
+
+# 5. Create GitHub release manually or let the workflow handle it
+```
+
+## Pre-release Process
+
+For testing releases before stable versions:
+
+1. Use pre-release tags: `v0.2.0-alpha.1`, `v0.2.0-beta.1`, `v0.2.0-rc.1`
+2. Mark as pre-release in GitHub
+3. Test thoroughly before creating stable release
+
+## Updating CHANGELOG.md
+
+Before each release, update `CHANGELOG.md`:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New features
+
+### Changed
+- Modifications to existing features
+
+### Fixed
+- Bug fixes
+
+### Removed
+- Removed features
+
+### Security
+- Security improvements
+```
+
+## Installation Instructions for Users
+
+With stable releases, users can now install specific versions:
+
+### Using pip
+```bash
+# Latest stable release
+pip install git+https://github.com/perplexityai/pplx-kernels.git
+
+# Specific version
+pip install git+https://github.com/perplexityai/[email protected]
+```
+
+### Using requirements.txt
+```
+# Pin to specific version
+git+https://github.com/perplexityai/[email protected]
+
+# Use version range (when published to PyPI)
+pplx-kernels>=0.1.0,<0.2.0
+```
+
+### Using Poetry
+```toml
+[tool.poetry.dependencies]
+pplx-kernels = {git = "https://github.com/perplexityai/pplx-kernels.git", tag = "v0.1.0"}
+```
+
+## Migration Guide
+
+### For Existing Users
+
+If you're currently pinning to commit SHAs, migrate to version tags:
+
+**Before:**
+```bash
+pip install git+https://github.com/perplexityai/pplx-kernels.git@2bd6e30fab358829bd01d1c0907be8088ff9e5e1
+```
+
+**After:**
+```bash
+pip install git+https://github.com/perplexityai/[email protected]
+```
+
+## Hotfix Process
+
+For critical fixes that need immediate release:
+
+1. Create hotfix branch from the release tag
+2. Apply minimal fix
+3. Increment patch version (e.g., v0.1.0 → v0.1.1)
+4. Follow normal release process
+5. Merge back to main branch
+
+## Release Checklist
+
+- [ ] Update version in `pyproject.toml`
+- [ ] Update `CHANGELOG.md` with new version
+- [ ] Test build and installation locally
+- [ ] Run full test suite
+- [ ] Create and push Git tag
+- [ ] Create GitHub release with release notes
+- [ ] Verify release artifacts
+- [ ] Update documentation if needed
+- [ ] Announce release (if applicable)
+
+## Troubleshooting
+
+### Version Conflicts
+If you encounter version conflicts, ensure `pyproject.toml` version matches the Git tag.
+
+### Failed Builds
+Check that all dependencies are properly specified and the build environment is correct.
+
+### Missing Tags
+Ensure tags are pushed to the remote repository: `git push origin --tags`
+
+## Future Improvements
+
+- PyPI publishing for easier installation
+- Automated changelog generation from commit messages
+- Integration with package managers
+- Automated testing for each release