Developer Guide - Dual Release System

Note: This is the developer documentation. For end-user documentation, see README.md

🎯 Overview

This repository maintains a single codebase that publishes to two separate NPM packages:

• @tawasal/node - Tawasal-branded SDK
• @nija/node - Nija-branded SDK (no Tawasal references)

🏗️ Architecture

Single Codebase (src/)
        │
        ├─────────────────┬─────────────────┐
        │                 │                 │
        ▼                 ▼                 ▼
   Source Code      README Files      Workflows
        │                 │                 │
        │          ┌──────┴──────┐         │
        │          │             │         │
        ▼          ▼             ▼         ▼
    dist/    README.tawasal  README.nija  GitHub Actions
        │          │             │         │
        └──────────┴─────────────┴─────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
        ▼                       ▼
  @tawasal/node            @nija/node
  (NPM Package)           (NPM Package)

📦 What Gets Published

Common (Both Packages)

• ✅ Same source code (src/)
• ✅ Same compiled output (dist/)
• ✅ Same version number
• ✅ Same functionality

Different (Per Package)

• ❌ Package name (@tawasal/node vs @nija/node)
• ❌ README content (branding)
• ❌ NPM account/token
• ❌ Git tags (-tawasal vs -nija suffix)

🚀 How to Release

Option 1: GitHub Actions (Recommended)

Tawasal Release

1. Navigate to Actions tab
2. Select "Publish Tawasal" workflow
3. Click "Run workflow"
4. Select version bump: major | minor | patch
5. Click "Run workflow" button

Nija Release

1. Navigate to Actions tab
2. Select "Publish Nija" workflow
3. Click "Run workflow"
4. Select version bump: major | minor | patch
5. Click "Run workflow" button

Option 2: NPM Scripts (Local Testing)

# Switch README
npm run readme:tawasal  # Switch to Tawasal README
npm run readme:nija     # Switch to Nija README

# Build
npm run build

# Lint
npm run lint

🔧 Development Workflow

1. Making Changes

# 1. Create feature branch
git checkout -b feature/my-feature

# 2. Make changes to source code
vim src/tawasal.ts

# 3. Update BOTH README files
vim README.tawasal.md  # Add Tawasal-specific docs
vim README.nija.md     # Add Nija-specific docs (no Tawasal refs)

# 4. Test locally
npm run build
npm run lint

# 5. Commit and push
git add .
git commit -m "feat: add new feature"
git push origin feature/my-feature

# 6. Create PR and merge to main

2. Releasing

# After PR is merged to main:

# Option A: Release both packages
1. Run "Publish Tawasal" workflow (patch)
2. Run "Publish Nija" workflow (patch)

# Option B: Release only one package
1. Run only the needed workflow

# Result:
# @tawasal/[email protected] published
# @nija/[email protected] published

📝 README Management

Structure

README.md              ← Active README (swapped during release)
README.tawasal.md      ← Tawasal version (source of truth for Tawasal)
README.nija.md         ← Nija version (source of truth for Nija)
README.DEVELOPERS.md   ← This file (for developers)

Rules

1. Never edit README.md directly - it gets overwritten
2. Always update both README.tawasal.md and README.nija.md
3. Keep shared sections synchronized
4. Remove Tawasal references from README.nija.md

Example: Adding New Feature Documentation

# 1. Add to Tawasal README
cat >> README.tawasal.md << 'EOF'
## New Feature

This feature works with Tawasal SuperApp...

```javascript
import { newFeature } from '@tawasal/node';

EOF

2. Add to Nija README (without Tawasal references)

cat >> README.nija.md << 'EOF'

New Feature

This feature works with Nija SuperApp...

import { newFeature } from '@nija/node';

EOF

3. Commit both

git add README.*.md git commit -m "docs: add new feature documentation"

## 🔐 Secrets Configuration

### Required GitHub Secrets

| Secret Name | Purpose | How to Get |
|-------------|---------|------------|
| `NPM_TOKEN` | Publish @tawasal/node | `npm login` (Tawasal account) → `npm token create --type=automation` |
| `NIJA_NPM_TOKEN` | Publish @nija/node | `npm login` (Nija account) → `npm token create --type=automation` |

### Setting Up Secrets

1. Go to **Repository Settings**
2. Navigate to **Secrets and variables** → **Actions**
3. Click **"New repository secret"**
4. Add each secret with its value

## 🧪 Testing

### Local Build Test

```bash
# Install dependencies
npm install

# Build
npm run build

# Verify output
ls -la dist/
cat dist/index.d.ts

README Swap Test

# Test Tawasal README
npm run readme:tawasal
head -n 10 README.md | grep -i tawasal

# Test Nija README
npm run readme:nija
head -n 10 README.md | grep -i nija

# Restore to Tawasal (default)
npm run readme:tawasal

Package.json Update Test (Nija)

# Simulate Nija package.json update
node -e "
const fs = require('fs');
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
console.log('Before:', pkg.name);
pkg.name = '@nija/node';
console.log('After:', pkg.name);
fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));
"

# Verify
cat package.json | grep '"name"'

# Restore
git checkout package.json

📊 Version Management

Versioning Strategy

• Patch (X.X.1): Bug fixes, documentation updates
• Minor (X.1.0): New features, backward compatible
• Major (1.0.0): Breaking changes

Version Synchronization

Both packages share the same version number:

@tawasal/[email protected]
@nija/[email protected]

But have separate git tags:

v1.2.3-tawasal
v1.2.3-nija

Example Release Sequence

# Current version: 1.0.0

# Release patch to both
1. Publish Tawasal (patch) → v1.0.1-tawasal → @tawasal/[email protected]
2. Publish Nija (patch)    → v1.0.1-nija    → @nija/[email protected]

# Release minor to both
1. Publish Tawasal (minor) → v1.1.0-tawasal → @tawasal/[email protected]
2. Publish Nija (minor)    → v1.1.0-nija    → @nija/[email protected]

🐛 Troubleshooting

Issue: GitHub Action Fails

Solution:

1. Check workflow logs in Actions tab
2. Verify secrets are configured
3. Check NPM token hasn't expired
4. Try manual release (see DUAL_RELEASE_GUIDE.md)

Issue: Wrong README Published

Solution:

# Trigger new release with correct README
# The workflow will automatically use the right README

Issue: Version Conflict

Solution:

# Check current version
npm version

# Reset if needed
npm version 1.0.0 --no-git-tag-version
git add package.json package-lock.json
git commit -m "chore: reset version"
git push

Issue: Package.json Wrong After Nija Release

Solution:

# The workflow automatically restores it
# If manual fix needed:
git checkout package.json
git push

📚 Documentation Files

| File | Purpose | Audience | |------|---------|----------| | README.md | Active README (swapped) | End users | | README.tawasal.md | Tawasal README source | End users (Tawasal) | | README.nija.md | Nija README source | End users (Nija) | | README.DEVELOPERS.md | This file | Developers | | DUAL_RELEASE_SUMMARY.md | Quick start guide | Developers | | DUAL_RELEASE_GUIDE.md | Complete guide | Developers | | RELEASE_CHECKLIST.md | Release checklist | Release managers | | ARCHITECTURE.md | System architecture | Developers/DevOps | | REFRESH_TOKEN_GUIDE.md | Refresh token docs | End users |

🎓 Best Practices

1. Always test locally before releasing
2. Update both READMEs when adding features
3. Use semantic versioning consistently
4. Keep versions synchronized between packages
5. Document breaking changes clearly
6. Test both packages after release
7. Monitor NPM downloads for both packages
8. Review GitHub Actions logs regularly

🔄 Maintenance Tasks

Weekly

• [ ] Check GitHub Actions for failed workflows
• [ ] Review NPM download stats
• [ ] Check for security vulnerabilities: npm audit

Monthly

• [ ] Update dependencies: npm update
• [ ] Review and update documentation
• [ ] Check NPM token expiration dates

Quarterly

• [ ] Review and update README files
• [ ] Audit GitHub secrets
• [ ] Review version strategy

🆘 Emergency Procedures

Unpublish Package (within 72 hours)

# Unpublish specific version
npm unpublish @tawasal/[email protected]
npm unpublish @nija/[email protected]

Deprecate Package

# Deprecate version
npm deprecate @tawasal/[email protected] "Use version 1.0.1 instead"
npm deprecate @nija/[email protected] "Use version 1.0.1 instead"

Rollback Release

# 1. Deprecate bad version
npm deprecate @tawasal/[email protected] "Critical bug, use 1.0.0"

# 2. Release fixed version
# Use GitHub Actions to release 1.0.2

📞 Support

• Tawasal Package Issues: [email protected]
• Nija Package Issues: [email protected]
• CI/CD Issues: [email protected]
• General Questions: Check documentation first

🔗 Useful Links

• NPM - @tawasal/node
• NPM - @nija/node
• GitHub Actions
• Repository Settings

Last Updated: 2025-08-07 Maintained By: Development Team