@odigos/ui-kit 0.0.10 → 0.0.11-1.patch-dev.361

package/README.md

@@ -1,12 +1,13 @@
 # Odigos UI Kit
 
 This library contains directories shared across multiple Odigos UIs, available import paths are:
-- components
+- components (re-usable and flexible)
 - constants
-- containers
+- containers (logic based sections)
 - functions
 - hooks
 - icons
+- snippets (re-usable but not flexible)
 - store
 - theme
 - types

package/VERSIONING.md

@@ -0,0 +1,228 @@
+# Versioning Guide
+
+This document explains how versioning and releases work for the `@odigos/ui-kit` package.
+
+## Overview
+
+The UI Kit uses a dual-release strategy:
+
+- **Main releases**: Stable versions published to the `latest` npm tag
+- **Dev releases**: Prerelease versions published to the `dev` npm tag
+
+## Release Types
+
+### 1. Main Releases (Stable)
+
+**Trigger**: Push/merge to `main` branch  
+**Workflow**: `.github/workflows/npm-publish.yml`  
+**NPM Tag**: `latest` (default)  
+**Version Format**: `MAJOR.MINOR.PATCH` (e.g., `1.8.0`)
+
+#### How it works:
+
+1. **Release Please**: Automatically manages versioning using conventional commits
+2. **Version Bumping**:
+   - `feat:` commits → minor version bump
+   - `fix:` commits → patch version bump
+   - `BREAKING CHANGE:` → major version bump
+3. **Release Process**:
+   - Creates a release PR with updated version and changelog
+   - After PR merge, automatically publishes to npm with `latest` tag
+
+#### Installation:
+
+```bash
+npm install @odigos/ui-kit
+# or
+npm install @odigos/ui-kit@latest
+```
+
+### 2. Dev Releases (Prerelease)
+
+**Trigger**: Push to `dev` branch  
+**Workflow**: `.github/workflows/publish-dev.yml`  
+**NPM Tag**: `dev`  
+**Version Format**: `MAJOR.MINOR.PATCH-dev.COMMIT_COUNT` (e.g., `1.8.0-dev.15`)
+
+#### How it works:
+
+1. **Automatic Triggering**: Runs on every push to the `dev` branch
+2. **Version Generation**:
+   - Takes current version from `package.json`
+   - Appends `-dev.{commit-count}` suffix
+   - Example: `0.0.110` → `0.0.110-dev.15`
+3. **Publishing**: Automatically publishes to npm with `dev` tag
+
+#### Installation:
+
+```bash
+npm install @odigos/ui-kit@dev
+```
+
+## Version Numbering
+
+### Current Version
+
+- **Current**: `0.0.110` (as of latest release)
+- **Format**: `MAJOR.MINOR.PATCH`
+- **Pre-major**: Currently in pre-major phase (0.x.x)
+
+### Version Bumping Rules
+
+#### Main Releases (via Release Please)
+
+- **Major** (`1.0.0`): Breaking changes (requires `BREAKING CHANGE:` in commit)
+- **Minor** (`0.1.0`): New features (requires `feat:` prefix)
+- **Patch** (`0.0.1`): Bug fixes (requires `fix:` prefix)
+
+#### Dev Releases
+
+- **Base Version**: Inherits from current `package.json` version
+- **Prerelease Suffix**: `-dev.{commit-count}`
+- **Incremental**: Each push to dev branch creates a new prerelease
+
+## Workflow Examples
+
+### Main Release Workflow
+
+```bash
+# 1. Make changes with conventional commits
+git commit -m "feat: add new button component"
+git commit -m "fix: resolve styling issue in modal"
+
+# 2. Push to main
+git push origin main
+
+# 3. Release Please creates PR automatically
+# 4. Merge PR → triggers npm publish to 'latest' tag
+```
+
+### Dev Release Workflow
+
+```bash
+# 1. Switch to dev branch
+git checkout dev
+
+# 2. Make experimental changes
+git commit -m "wip: experimental feature"
+git push origin dev
+
+# 3. Automatically publishes to npm with 'dev' tag
+# Version: 0.0.110-dev.16 (example)
+```
+
+## Installation Commands
+
+### Stable Release (Recommended for Production)
+
+```bash
+npm install @odigos/ui-kit
+```
+
+### Latest Dev Release (For Testing)
+
+```bash
+npm install @odigos/ui-kit@dev
+```
+
+### Specific Version
+
+```bash
+npm install @odigos/ui-kit@0.0.110
+npm install @odigos/ui-kit@0.0.110-dev.15
+```
+
+## Branch Strategy
+
+### `main` Branch
+
+- **Purpose**: Stable, production-ready code
+- **Releases**: Full releases with `latest` tag
+- **Versioning**: Managed by Release Please
+- **Usage**: Production applications
+
+### `dev` Branch
+
+- **Purpose**: Development and experimental features
+- **Releases**: Prerelease versions with `dev` tag
+- **Versioning**: Automatic with commit count
+- **Usage**: Testing and development
+
+## Configuration Files
+
+### Release Please Configuration
+
+- **File**: `release-please-config.json`
+- **Purpose**: Configures automatic versioning for main releases
+- **Settings**:
+  - `bump-minor-pre-major: true` - Minor bumps during pre-major phase
+  - `bump-patch-for-minor-pre-major: true` - Patch bumps for minor changes
+  - `release-type: "node"` - Node.js package release type
+
+### Package.json
+
+- **Version**: Current version (e.g., `0.0.110`)
+- **Release Branches**: `["main"]` - Only main branch creates releases
+- **Publish Config**: `"access": "public"` - Public npm package
+
+## Best Practices
+
+### For Main Releases
+
+1. **Use Conventional Commits**: Follow `feat:`, `fix:`, `BREAKING CHANGE:` format
+2. **Review Release PRs**: Check generated changelog and version
+3. **Test Before Merge**: Ensure all changes work correctly
+4. **Merge Release PRs**: Don't edit them manually
+
+### For Dev Releases
+
+1. **Experimental Features**: Use dev branch for testing new features
+2. **Frequent Pushes**: Each push creates a new prerelease
+3. **Clear Commit Messages**: Help track what changed in each dev release
+4. **Test Thoroughly**: Dev releases should be tested before promoting to main
+
+### For Consumers
+
+1. **Production**: Use `@latest` or no tag (stable releases)
+2. **Development**: Use `@dev` for testing new features
+3. **Specific Versions**: Pin to specific versions for reproducible builds
+4. **Update Strategy**: Regularly update to get latest fixes and features
+
+## Troubleshooting
+
+### Common Issues
+
+#### Dev Release Not Publishing
+
+- Check if `NPM_TOKEN` secret is configured in GitHub
+- Verify the workflow is running on dev branch pushes
+- Check GitHub Actions logs for errors
+
+#### Version Conflicts
+
+- Dev releases use commit count, so conflicts are unlikely
+- Main releases use Release Please, which handles conflicts automatically
+
+#### Installation Issues
+
+- Use `npm install @odigos/ui-kit@dev` for dev releases
+- Use `npm install @odigos/ui-kit` for stable releases
+- Clear npm cache if needed: `npm cache clean --force`
+
+## Release History
+
+Current version: `0.0.110`
+
+### Recent Releases
+
+- Check [GitHub Releases](https://github.com/odigos-io/ui-kit/releases) for full history
+- Dev releases are not tracked in GitHub releases (npm only)
+
+## Support
+
+For questions about versioning or releases:
+
+1. Check this documentation
+2. Review GitHub Actions logs
+3. Check npm package page: https://www.npmjs.com/package/@odigos/ui-kit
+4. Open an issue in the repository