# Publishing Guide for @everytravel/shared

This guide covers the complete process for publishing new versions of the `@everytravel/shared` package to npm.

## 📋 Prerequisites

### 1. NPM Account Setup
- Ensure you're logged into npm: `npm whoami`
- Verify organization access: `npm org ls everytravel`
- You should be listed as an owner or maintainer

### 2. Package Structure Validation
Before publishing, ensure:
- All models are properly exported in `models/index.js`
- All CRUD operations are properly exported in their respective directories
- README.md is up to date with current functionality
- Package.json has correct version and metadata

## 🔄 Versioning Strategy

### Semantic Versioning (SemVer)
We follow [Semantic Versioning 2.0.0](https://semver.org/) with the format: `MAJOR.MINOR.PATCH`

- **MAJOR** (X.0.0): Breaking changes, incompatible API changes
- **MINOR** (0.X.0): New features, backward compatible additions
- **PATCH** (0.0.X): Bug fixes, backward compatible patches

### Version Bumping Commands

```bash
# For bug fixes and minor updates (0.0.X)
npm version patch

# For new features (0.X.0)
npm version minor

# For breaking changes (X.0.0)
npm version major
```

### Version Examples

| Change Type | Command | Version Change | Description |
|-------------|---------|----------------|-------------|
| Bug fix | `npm version patch` | 1.0.0 → 1.0.1 | Fixed CRUD operation error handling |
| New feature | `npm version minor` | 1.0.1 → 1.1.0 | Added new model or CRUD method |
| Breaking change | `npm version major` | 1.1.0 → 2.0.0 | Changed model structure or API |

## 🚀 Publishing Process

### Step 1: Pre-Publish Checklist

```bash
# 1. Check current version
npm version

# 2. Validate package structure
npm pack --dry-run

# 3. Check for any linting issues
# (Add your preferred linting tool)

# 4. Update README.md if needed
# 5. Update CHANGELOG.md if you have one
```

### Step 2: Version Bumping

```bash
# Choose appropriate version bump
npm version patch  # or minor or major

# This will:
# - Update package.json version
# - Create a git tag
# - Commit the changes
```

### Step 3: Publishing

```bash
# Publish to npm (public access)
npm publish --access public

# Or for private packages (when ready)
npm publish --access restricted
```

### Step 4: Verification

```bash
# Verify package is published
npm view @everytravel/shared

# Test installation
npm install @everytravel/shared --dry-run

# Check package contents
npm pack --dry-run
```

## 📦 Package Configuration

### Package.json Requirements

```json
{
  "name": "@everytravel/shared",
  "version": "1.0.0",
  "description": "A comprehensive shared package for Everytravel...",
  "type": "module",
  "main": "index.js",
  "exports": {
    "./models": "./models/index.js",
    "./methods": "./methods/index.js",
    "./create": "./create/index.js",
    "./read": "./read/index.js",
    "./update": "./update/index.js",
    "./delete": "./delete/index.js"
  },
  "keywords": ["everytravel", "shared", "models", "methods", "crud"],
  "author": "Everytravel Team",
  "license": "ISC",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/everytravel/shared.git"
  },
  "homepage": "https://github.com/everytravel/shared#readme",
  "bugs": {
    "url": "https://github.com/everytravel/shared/issues"
  },
  "dependencies": {
    "mongoose": "^8.0.3"
  },
  "engines": {
    "node": ">=16.0.0"
  }
}
```

### .npmignore Configuration

Ensure `.npmignore` excludes:
- Development files (`.git/`, `.gitignore`, etc.)
- IDE files (`.vscode/`, `.idea/`)
- OS files (`.DS_Store`, `Thumbs.db`)
- Logs and temporary files
- Test files and coverage reports
- Environment files (`.env*`)

## 🔐 Access Control

### Public vs Private Packages

```bash
# Make package public (current state)
npm publish --access public

# Make package private (when ready)
npm access restricted @everytravel/shared

# Make package public again
npm access public @everytravel/shared
```

### Organization Management

```bash
# List organization members
npm org ls everytravel

# Add team member
npm org add everytravel <username> developer

# Remove team member
npm org rm everytravel <username>
```

## 🛠️ Development Workflow

### 1. Feature Development
```bash
# Create feature branch
git checkout -b feature/new-model

# Make changes
# Update models, CRUD operations, tests

# Commit changes
git add .
git commit -m "feat: add new UserProfile model"
```

### 2. Testing Before Publish
```bash
# Test locally
npm pack
npm install ./everytravel-shared-1.0.0.tgz --dry-run

# Test in a sample project
cd ../test-project
npm install ../shared/everytravel-shared-1.0.0.tgz
```

### 3. Publishing
```bash
# Merge to main branch
git checkout main
git merge feature/new-model

# Bump version
npm version minor

# Publish
npm publish --access public

# Push tags
git push --tags
```

## 📝 Documentation Updates

### Required Documentation Updates

Before each publish, ensure:

1. **README.md** is updated with:
   - New models or methods
   - Updated examples
   - Correct import statements
   - Current version compatibility

2. **CHANGELOG.md** (if maintained):
   - List of changes in new version
   - Breaking changes clearly marked
   - Migration guides if needed

3. **JSDoc Comments**:
   - All new functions documented
   - Parameter types specified
   - Return types documented

## 🚨 Common Issues & Solutions

### Issue: "Package name already exists"
```bash
# Check if package exists
npm view @everytravel/shared

# Ensure you're using the correct organization scope
# Package should be @everytravel/shared, not just shared
```

### Issue: "Access denied"
```bash
# Check organization membership
npm org ls everytravel

# Ensure you're logged in
npm whoami

# Re-authenticate if needed
npm login
```

### Issue: "Invalid package.json"
```bash
# Validate package.json
npm pkg fix

# Check for syntax errors
node -e "JSON.parse(require('fs').readFileSync('package.json'))"
```

### Issue: "Files not included in package"
```bash
# Check .npmignore
cat .npmignore

# Test package contents
npm pack --dry-run

# Ensure files aren't being ignored
```

## 🔄 Rollback Process

### Unpublishing (Within 72 hours)
```bash
# Unpublish specific version
npm unpublish @everytravel/shared@1.0.1

# Unpublish entire package (use with caution)
npm unpublish @everytravel/shared --force
```

### Deprecating Versions
```bash
# Deprecate specific version
npm deprecate @everytravel/shared@1.0.0 "Use version 1.1.0 instead"
```

## 📊 Monitoring & Maintenance

### Package Analytics
- Monitor downloads: `npm view @everytravel/shared`
- Check for issues on GitHub
- Monitor dependency updates

### Regular Maintenance
- Update dependencies: `npm update`
- Check for security vulnerabilities: `npm audit`
- Review and update documentation

## 🎯 Best Practices

### Before Publishing
1. ✅ Test all CRUD operations
2. ✅ Validate all model schemas
3. ✅ Update documentation
4. ✅ Check for breaking changes
5. ✅ Test in a sample project

### Version Management
1. ✅ Use semantic versioning
2. ✅ Document breaking changes
3. ✅ Maintain changelog
4. ✅ Tag releases in git

### Quality Assurance
1. ✅ Code review completed
2. ✅ Tests passing
3. ✅ Documentation updated
4. ✅ Examples verified

## 📞 Support

For publishing issues:
1. Check npm status: https://status.npmjs.org/
2. Review npm documentation: https://docs.npmjs.com/
3. Contact organization admin if access issues persist

---

**Remember**: Always test thoroughly before publishing, and communicate breaking changes clearly to users of the package.