# Release Guide

This guide provides step-by-step instructions for releasing new versions of the RAG Chatbot Library.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Release Types](#release-types)
- [Release Process](#release-process)
- [Manual Release Steps](#manual-release-steps)
- [Testing Before Release](#testing-before-release)
- [Post-Release Tasks](#post-release-tasks)
- [Rollback Process](#rollback-process)

## Prerequisites

Before releasing, ensure you have:

1. **Development Environment Set Up**

   - Node.js 16+ installed
   - Git configured with proper credentials
   - Access to the repository with push permissions

2. **Quality Checks Passed**

   - All tests passing (`npm test`)
   - No linting errors (`npm run lint`)
   - TypeScript compilation successful (`npm run build`)
   - Manual testing completed

3. **Documentation Updated**
   - README.md reflects new features
   - API documentation is current
   - CHANGELOG.md is ready for update

## Release Types

Following [Semantic Versioning](https://semver.org/):

### Patch Release (x.x.X)

**For bug fixes and security patches**

Examples:

- Fix memory leak in document processing
- Correct TypeScript type definitions
- Security vulnerability patches
- Documentation corrections

```bash
npm run release patch
```

### Minor Release (x.X.0)

**For new features that are backward compatible**

Examples:

- New React hooks
- Additional component props
- New LLM provider support
- Performance improvements
- New optional configuration options

```bash
npm run release minor
```

### Major Release (X.0.0)

**For breaking changes that require code modifications**

Examples:

- API signature changes
- Removal of deprecated features
- Required configuration changes
- Component prop changes that break existing usage

```bash
npm run release major
```

## Release Process

### Automated Release Script

Use the release script for streamlined releases:

```bash
# Navigate to chatbot directory
cd src/lib/chatbot

# Run release script
node scripts/release.js [patch|minor|major]

# Example: patch release
node scripts/release.js patch
```

The script will:

1. ✅ Check git status (must be clean)
2. 🧪 Run test suite
3. 🔨 Build the package
4. 📦 Update version number
5. 📋 Provide next steps

### Package.json Scripts

Alternative npm scripts:

```bash
# Build and test
npm run build:package
npm test

# Version bump (choose one)
npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0
```

## Manual Release Steps

### 1. Pre-Release Preparation

```bash
# Ensure clean working directory
git status

# Pull latest changes
git pull origin main

# Install dependencies
npm install

# Run full test suite
npm test

# Run type checking
npm run typecheck

# Build the library
npm run build:package
```

### 2. Version Update

```bash
# Update version (choose appropriate type)
npm version patch --no-git-tag-version

# Or manually edit package.json and update version field
```

### 3. Update Documentation

**Update CHANGELOG.md:**

```markdown
## [1.0.1] - 2024-01-15

### Fixed

- Fixed memory leak in document processing
- Corrected TypeScript type definitions

### Added

- New error handling examples in documentation
```

**Update README.md if needed:**

- Installation instructions
- New features documentation
- Updated examples

### 4. Commit and Tag

```bash
# Stage all changes
git add .

# Commit with semantic message
git commit -m "Release v1.0.1

- Fixed memory leak in document processing
- Corrected TypeScript type definitions
- Updated documentation"

# Create git tag
git tag v1.0.1

# Push changes and tags
git push origin main
git push origin v1.0.1
```

### 5. Verify Release

```bash
# Check that tag was created
git tag -l

# Verify package.json version
cat package.json | grep version

# Test installation locally
npm pack
```

## Testing Before Release

### 1. Automated Tests

```bash
# Unit tests
npm test

# Coverage report
npm run test:coverage

# Type checking
npm run typecheck
```

### 2. Integration Testing

```bash
# Build library
npm run build:package

# Test in example project
cd ../../../examples/basic-chat
npm install
npm run build
```

### 3. Manual Testing Checklist

- [ ] **Basic Functionality**

  - [ ] Chat widget renders correctly
  - [ ] Messages send and receive
  - [ ] Document upload works
  - [ ] Search functionality operates

- [ ] **Error Handling**

  - [ ] Invalid API keys handled gracefully
  - [ ] Network errors display properly
  - [ ] File upload errors are caught

- [ ] **UI/UX**

  - [ ] Responsive design works
  - [ ] Theme switching functions
  - [ ] Accessibility features work

- [ ] **Performance**
  - [ ] No memory leaks detected
  - [ ] Bundle size is acceptable
  - [ ] Loading times are reasonable

### 4. Cross-Environment Testing

```bash
# Test different Node versions
nvm use 16 && npm test
nvm use 18 && npm test
nvm use 20 && npm test

# Test different React versions (if applicable)
npm install react@17 react-dom@17 && npm test
npm install react@18 react-dom@18 && npm test
```

## Post-Release Tasks

### 1. Update Documentation

- [ ] Update main README.md with new version
- [ ] Update integration examples
- [ ] Update API documentation if needed
- [ ] Create release notes for major releases

### 2. Communication

- [ ] Announce release in team channels
- [ ] Update project documentation
- [ ] Notify users of breaking changes (major releases)

### 3. Monitor Release

- [ ] Check for issues in first 24 hours
- [ ] Monitor error tracking services
- [ ] Review user feedback
- [ ] Address urgent issues with patch releases

## Rollback Process

If a release needs to be rolled back:

### 1. Immediate Rollback

```bash
# Revert the release commit
git revert <release-commit-hash>

# Remove the tag
git tag -d v1.0.1
git push origin :refs/tags/v1.0.1

# Create patch release with fix
npm version patch
git add .
git commit -m "Rollback v1.0.1 - critical issue found"
git tag v1.0.2
git push origin main --tags
```

### 2. Fix and Re-release

```bash
# Fix the issue
# ... make necessary changes ...

# Test thoroughly
npm test

# Create new patch release
npm version patch
git add .
git commit -m "Fix critical issue from v1.0.1"
git tag v1.0.2
git push origin main --tags
```

## Release Checklist Template

Copy this checklist for each release:

```markdown
## Release v[X.Y.Z] Checklist

### Pre-Release

- [ ] All tests passing
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Manual testing completed
- [ ] Breaking changes documented (if any)

### Release

- [ ] Version bumped correctly
- [ ] Git tag created
- [ ] Changes pushed to main branch
- [ ] Release notes created (if major/minor)

### Post-Release

- [ ] Release announced
- [ ] Documentation updated
- [ ] Monitoring for issues
- [ ] User feedback collected
```

## Version History

Track major milestones:

| Version | Date       | Type  | Description     |
| ------- | ---------- | ----- | --------------- |
| 1.0.0   | 2024-01-01 | Major | Initial release |
| 1.0.1   | 2024-01-15 | Patch | Bug fixes       |
| 1.1.0   | 2024-02-01 | Minor | New features    |

## Support

For release-related questions:

- 📧 Development Team: dev@restnfeel.com
- 🐛 Report Issues: [GitHub Issues](https://github.com/restnfeel/agentc-starter-kit/issues)
- 📖 Documentation: [API Docs](./API.md)