---
name: Package Development Lifecycle
description: This skill should be used when the user asks about "package development workflow", "release process", "beta testing", "package versioning", "CumulusCI", "CI/CD for packages", or needs guidance on the end-to-end package development process from design through release.
version: 0.1.0
---

# Package Development Lifecycle

## Overview

The package development lifecycle encompasses the complete workflow from initial design through production release and ongoing maintenance. This skill provides step-by-step guidance for developing second-generation managed packages (2GP) with focus on scratch org development, version management, beta testing, and automated CI/CD workflows.

Follow this lifecycle to deliver production-grade managed packages that scale, maintain backward compatibility, and support seamless customer upgrades.

## Lifecycle Phases

The package development lifecycle consists of six interconnected phases:

1. **Design & Planning** - Define requirements, architecture, and release strategy
2. **Development** - Build features in scratch orgs with version control
3. **Testing** - Validate functionality, integration, and upgrade paths
4. **Packaging** - Create versioned package artifacts
5. **Beta Release** - Deploy to test environments and gather feedback
6. **Release & Maintenance** - Publish to production and manage patches

## Phase 1: Design & Planning

### Define Package Requirements

Start every package development cycle with clear requirements and architectural planning.

**Key Activities:**

1. **Identify package scope and boundaries**
   - Define what functionality belongs in the package
   - Determine dependencies on other packages or platform features
   - Plan for extensibility and customization points

2. **Apply Well Architected Framework**
   - Review all five pillars (Trusted, Easy, Adaptable, Composable, Connected)
   - Document architectural decisions with pillar justifications
   - Use decision matrices for tradeoff analysis

3. **Plan version strategy**
   - Determine if this is a major, minor, or patch release
   - Identify breaking changes vs. backward-compatible enhancements
   - Plan deprecation strategy for removed features

4. **Define success criteria**
   - Test coverage requirements (>90% for production)
   - Performance benchmarks
   - Security and compliance requirements

**Outputs:**
- Package requirements document
- Architecture diagrams
- Version number (MAJOR.MINOR.PATCH format)
- Release notes outline

### Create Development Plan

Translate requirements into actionable development tasks.

**Key Activities:**

1. **Break down features into metadata components**
   - Objects, fields, relationships
   - Apex classes, triggers, test classes
   - Lightning Web Components
   - Flows, permission sets, custom metadata

2. **Sequence development work**
   - Build foundational components first (domain model, services)
   - Add business logic and integrations
   - Implement UI last

3. **Plan test strategy**
   - Unit tests for all Apex classes
   - Integration tests for end-to-end flows
   - Upgrade tests for existing customer scenarios

**Outputs:**
- Development task breakdown
- Test plan
- Timeline and milestones

## Phase 2: Development

### Setup Development Environment

Establish scratch org based development with proper source control.

**Initial Setup:**

```bash
# Initialize SFDX project (if new)
sf project generate --name my-package

# Configure sfdx-project.json with package definition
# Edit sfdx-project.json to add packageDirectories
```

**sfdx-project.json structure:**

```json
{
  "packageDirectories": [
    {
      "path": "force-app",
      "package": "MyPackage",
      "versionName": "Spring '26",
      "versionNumber": "1.2.0.NEXT",
      "default": true
    }
  ],
  "namespace": "mypkg",
  "sourceApiVersion": "62.0",
  "packageAliases": {
    "MyPackage": "0Ho..."
  }
}
```

**Create scratch org definition:**

```json
// config/project-scratch-def.json
{
  "orgName": "MyPackage Development",
  "edition": "Developer",
  "features": ["EnableSetPasswordInApi"],
  "settings": {
    "lightningExperienceSettings": {
      "enableS1DesktopEnabled": true
    }
  }
}
```

### Develop in Scratch Orgs

Use scratch orgs as isolated, reproducible development environments.

**Daily Development Workflow:**

1. **Create feature branch**
   ```bash
   git checkout -b feature/new-capability
   ```

2. **Create scratch org**
   ```bash
   sf org create scratch \
     --definition-file config/project-scratch-def.json \
     --alias my-feature \
     --set-default \
     --duration-days 7
   ```

3. **Push source to scratch org**
   ```bash
   sf project deploy start --source-dir force-app
   ```

4. **Develop and test**
   - Make changes in scratch org (VS Code, Setup UI)
   - Pull changes back to local project
   ```bash
   sf project retrieve start --source-dir force-app
   ```

5. **Run tests continuously**
   ```bash
   sf apex run test --test-level RunLocalTests --result-format human
   ```

6. **Commit changes**
   ```bash
   git add .
   git commit -m "Add new capability"
   ```

7. **Push to remote**
   ```bash
   git push origin feature/new-capability
   ```

**Best Practices:**

- Create new scratch org for each feature or bug fix
- Keep scratch orgs short-lived (7-14 days max)
- Delete scratch orgs when feature is complete
- Never develop directly in packaging org or production

### Apply Enterprise Patterns

Structure code using service, domain, and selector layers.

**Service Layer:**
- Business logic orchestration
- Transaction boundaries
- External API integration

**Domain Layer:**
- Business rules and validations
- SObject behavior encapsulation
- Trigger handlers

**Selector Layer:**
- SOQL query centralization
- Data access optimization
- Selective query filters

Consult the `apex-enterprise-patterns` skill for detailed implementation guidance.

### Version Control Strategy

Maintain clean git history with meaningful commits.

**Branch Strategy:**

- `main` - Production-ready code
- `develop` - Integration branch for next release
- `feature/*` - Individual feature development
- `hotfix/*` - Urgent production fixes

**Commit Guidelines:**

- Write descriptive commit messages
- Reference issue/work item numbers
- Keep commits atomic (single logical change)
- Squash feature branches before merging

## Phase 3: Testing

### Unit Testing

Achieve comprehensive test coverage with meaningful assertions.

**Test Class Requirements:**

```apex
@IsTest
private class AccountServiceTest {
    @TestSetup
    static void setup() {
        // Create test data
    }

    @IsTest
    static void testPositiveScenario() {
        // Test expected behavior
        Test.startTest();
        // Execute code under test
        Test.stopTest();
        // Assert expected results
    }

    @IsTest
    static void testNegativeScenario() {
        // Test error handling
    }

    @IsTest
    static void testBulkScenario() {
        // Test with 200 records
    }
}
```

**Coverage Targets:**

- Overall package coverage: >90%
- Every Apex class: >75%
- All exception handlers tested
- Bulk operations validated (200+ records)

### Integration Testing

Validate end-to-end workflows and cross-component interactions.

**Integration Test Approach:**

1. **Setup test data representing real scenarios**
   - Multiple related objects
   - Permission set assignments
   - Custom metadata configuration

2. **Execute complete workflows**
   - User actions through UI
   - API calls with full payloads
   - Scheduled batch jobs

3. **Validate outcomes across components**
   - Database state
   - Platform events published
   - External callouts made

**Run integration tests:**

```bash
sf apex run test \
  --test-level RunSpecifiedTests \
  --class-names IntegrationTestSuite \
  --result-format human
```

### Upgrade Testing

Ensure new versions work seamlessly with existing customer installations.

**Upgrade Scenarios:**

1. **Fresh installation** - New customer with no prior version
2. **Upgrade from previous version** - Existing customer updating
3. **Skipped version upgrade** - Customer jumping multiple versions
4. **Data migration** - Schema changes requiring data transformation

**Upgrade Test Process:**

1. **Install previous package version in scratch org**
   ```bash
   sf package install --package 04t... --wait 20
   ```

2. **Setup customer-like configuration**
   - Create custom fields on package objects (if allowed)
   - Configure custom metadata
   - Insert test data

3. **Upgrade to new version**
   ```bash
   sf package install --package 04t... --wait 20 --upgrade-type mixed
   ```

4. **Validate upgrade success**
   - All data preserved
   - New features available
   - No errors in debug logs
   - Custom configurations intact

**Handle breaking changes:**

- Use deprecation warnings for features to remove
- Provide migration scripts in package install script
- Document upgrade steps in release notes

## Phase 4: Packaging

### Create Package Version

Generate installable package artifacts with proper versioning.

**Package Version Creation:**

```bash
# Create package version (beta or released)
sf package version create \
  --package "MyPackage" \
  --version-name "Spring '26" \
  --version-number "1.2.0.NEXT" \
  --installation-key-bypass \
  --wait 30 \
  --code-coverage
```

**Version Numbering (MAJOR.MINOR.PATCH):**

- **MAJOR** - Breaking changes, incompatible API changes
- **MINOR** - New functionality, backward-compatible
- **PATCH** - Bug fixes, backward-compatible

**Example version progression:**
- 1.0.0 - Initial release
- 1.1.0 - Added new feature
- 1.1.1 - Fixed bug in 1.1.0
- 2.0.0 - Breaking change (removed deprecated API)

**Package creation output:**

```
Package version creation request:
  Package Version Create Request ID: 08c...
  Status: Success
  Package Version ID: 04t...
  Version: 1.2.0.1
  Code Coverage: 94%
```

**Save package version ID:**

Update `sfdx-project.json` packageAliases:

```json
{
  "packageAliases": {
    "MyPackage": "0Ho...",
    "MyPackage@1.2.0-1": "04t..."
  }
}
```

### Validate Package

Verify package installation and functionality before beta release.

**Validation Checklist:**

1. **Install in fresh scratch org**
   ```bash
   sf package install --package "MyPackage@1.2.0-1" --wait 20
   ```

2. **Verify all components installed**
   - Check Setup > Installed Packages
   - Review component list in package details

3. **Run smoke tests**
   - Execute critical user workflows
   - Validate no permission errors
   - Check debug logs for exceptions

4. **Test uninstallation**
   - Uninstall package
   - Verify clean removal (no orphaned metadata)

## Phase 5: Beta Release

### Promote to Beta

Release package to beta testers for early feedback.

**Beta Release Process:**

1. **Create beta package version** (done in Phase 4)

2. **Share beta installation link**
   ```
   https://login.salesforce.com/packaging/installPackage.apexp?p0=04t...
   ```

3. **Provide beta documentation**
   - Installation instructions
   - Known limitations
   - How to provide feedback

**Beta Testing Scope:**

- Limited audience (select customers or partners)
- Non-production environments only
- Time-boxed testing period (2-4 weeks)
- Clear feedback channels (email, issues tracker)

### Gather Feedback

Collect structured feedback from beta testers.

**Feedback Collection:**

1. **Setup feedback mechanisms**
   - GitHub Issues for bug reports
   - Survey for feature feedback
   - Scheduled check-in calls

2. **Monitor beta installations**
   - Track installation success/failures
   - Review error logs from beta orgs
   - Monitor support cases

3. **Prioritize feedback**
   - Critical bugs - Must fix before release
   - Enhancement requests - Consider for next version
   - Edge cases - Document as known limitations

**Beta Exit Criteria:**

- Zero critical bugs
- >85% beta tester satisfaction
- All planned features validated
- Upgrade path tested successfully

## Phase 6: Release & Maintenance

### Promote to Released

Publish package for general availability.

**Release Promotion:**

```bash
# Promote package version from beta to released
sf package version promote --package "MyPackage@1.2.0-1"
```

**Release Activities:**

1. **Update AppExchange listing** (if applicable)
   - New version number
   - Updated release notes
   - New screenshots/videos

2. **Publish release notes**
   - New features
   - Bug fixes
   - Known issues
   - Upgrade instructions

3. **Notify customers**
   - Email announcement
   - In-app notifications
   - AppExchange listing update

4. **Tag release in git**
   ```bash
   git tag -a v1.2.0 -m "Release 1.2.0 - Spring '26"
   git push origin v1.2.0
   ```

### Monitor Post-Release

Track adoption and identify issues quickly.

**Post-Release Monitoring:**

1. **Track installations**
   - Monitor installation success rate
   - Identify common installation errors

2. **Review support cases**
   - Categorize issues by severity
   - Identify patterns in bug reports

3. **Analyze usage metrics** (if instrumented)
   - Feature adoption rates
   - Performance metrics
   - Error rates

**Issue Response:**

- **Critical bugs**: Create hotfix immediately
- **Major bugs**: Schedule patch release
- **Minor bugs**: Include in next planned release

### Patch Management

Address production issues with targeted fixes.

**Hotfix Process:**

1. **Create hotfix branch from release tag**
   ```bash
   git checkout -b hotfix/1.2.1 v1.2.0
   ```

2. **Develop fix in scratch org**
   - Minimal code changes
   - Focus only on bug fix
   - Comprehensive test coverage

3. **Create patch version**
   ```bash
   sf package version create \
     --package "MyPackage" \
     --version-number "1.2.1.NEXT" \
     --skip-validation
   ```

4. **Test patch thoroughly**
   - Install over 1.2.0 in scratch org
   - Validate fix works
   - Ensure no regressions

5. **Release patch**
   ```bash
   sf package version promote --package "MyPackage@1.2.1-1"
   ```

6. **Merge hotfix back**
   ```bash
   git checkout main
   git merge hotfix/1.2.1
   git checkout develop
   git merge hotfix/1.2.1
   ```

**Patch Version Criteria:**

- Only bug fixes (no new features)
- Backward compatible
- Rapid release cycle (days, not weeks)
- Clear documentation of what was fixed

## CumulusCI Integration

CumulusCI provides automation for the entire package development lifecycle.

### Why CumulusCI

**Key Benefits:**

- **Automated workflows** - Standardized development tasks
- **Dependency management** - Handle package dependencies automatically
- **Scratch org management** - Preconfigured org setups
- **CI/CD integration** - GitHub Actions, Jenkins, CircleCI
- **Testing automation** - Robot Framework integration
- **Release orchestration** - Automated release processes

### Basic Setup

**Install CumulusCI:**

```bash
pip install cumulusci
cci project init
```

**Configure cumulusci.yml:**

```yaml
project:
    name: MyPackage
    package:
        name: MyPackage
        namespace: mypkg
        api_version: '62.0'
    git:
        default_branch: main
    dependencies:
        - github: https://github.com/SalesforceFoundation/NPSP

orgs:
    scratch:
        dev:
            config_file: config/project-scratch-def.json
            days: 7
        qa:
            config_file: config/qa-scratch-def.json
            days: 30

flows:
    dev_org:
        steps:
            1:
                task: create_package
            2:
                task: deploy
            3:
                task: assign_permission_sets
            4:
                task: load_sample_data
```

### Common CumulusCI Workflows

**Create development org:**

```bash
cci flow run dev_org --org dev
```

**Run tests:**

```bash
cci task run run_tests --org dev
```

**Build and release:**

```bash
cci flow run release_beta --org packaging
```

For detailed CumulusCI configuration, task reference, and CI/CD integration patterns, consult `references/cumulusci-guide.md`.

## CI/CD Best Practices

### Continuous Integration

Automate testing and validation on every commit.

**GitHub Actions Example:**

```yaml
name: CI
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install SF CLI
        run: npm install -g @salesforce/cli
      - name: Authenticate
        run: sf org login jwt --username ${{ secrets.PACKAGING_ORG }}
      - name: Create package version
        run: sf package version create --wait 30 --code-coverage
      - name: Run tests
        run: sf apex run test --test-level RunLocalTests
```

**CI Pipeline Stages:**

1. **Lint and validate** - Check code quality
2. **Build package version** - Create package artifact
3. **Run unit tests** - Validate code coverage
4. **Integration tests** - End-to-end validation
5. **Upgrade tests** - Validate upgrade path

### Continuous Deployment

Automate package releases to different environments.

**Environment Strategy:**

- **Development** - Individual developer scratch orgs
- **Integration** - Shared scratch org for integration testing
- **QA** - Dedicated sandbox for QA team
- **UAT** - Customer preview environment
- **Production** - Released package version

**Deployment Automation:**

- Automatic beta release on merge to `develop`
- Manual promotion to released status
- Automated patch releases for hotfixes

## Release Checklist

Before promoting any package version to released status, complete the comprehensive release checklist.

Key validation areas:

- Code quality and test coverage
- Security and compliance review
- Documentation completeness
- Upgrade path validation
- Performance benchmarks met
- AppExchange requirements (if applicable)

For the complete release checklist with validation criteria, consult `references/release-checklist.md`.

## Common Pitfalls

### Development Anti-Patterns

**Avoid these mistakes:**

1. **Developing in packaging org** - Use scratch orgs instead
2. **Skipping upgrade tests** - Always test upgrade path
3. **Breaking changes without major version** - Follow semantic versioning
4. **Insufficient test coverage** - Target >90% for production
5. **Hardcoded configuration** - Use Custom Metadata instead
6. **Missing dependency management** - Document all dependencies

### Version Management Mistakes

**Common errors:**

1. **Inconsistent versioning** - Follow MAJOR.MINOR.PATCH strictly
2. **Promoting beta too early** - Complete beta testing first
3. **No rollback plan** - Always have downgrade strategy
4. **Skipping patch versions** - Address critical bugs immediately

### Release Process Issues

**Watch out for:**

1. **Incomplete release notes** - Document all changes
2. **Missing migration scripts** - Provide upgrade guidance
3. **No beta testing** - Validate with real users first
4. **Poor communication** - Notify customers of releases

## Quick Reference

### Package Version Commands

```bash
# Create package (one-time)
sf package create --name MyPackage --package-type Managed

# Create version
sf package version create --package MyPackage --wait 30

# Promote to released
sf package version promote --package MyPackage@1.2.0-1

# Install package
sf package install --package 04t... --wait 20

# List versions
sf package version list --package MyPackage
```

### Version Number Guide

| Change Type | Version | Example |
|-------------|---------|---------|
| Breaking change | MAJOR | 1.0.0 → 2.0.0 |
| New feature | MINOR | 1.0.0 → 1.1.0 |
| Bug fix | PATCH | 1.0.0 → 1.0.1 |

### Lifecycle Phase Summary

| Phase | Key Activities | Primary Tools |
|-------|----------------|---------------|
| Design | Requirements, architecture | Well Architected Framework |
| Development | Code, test in scratch orgs | SF CLI, VS Code |
| Testing | Unit, integration, upgrade tests | Apex Test Runner |
| Packaging | Create versions | `sf package version create` |
| Beta | Limited release, gather feedback | Beta installations |
| Release | Promote, publish, monitor | `sf package version promote` |

### When to Use This Skill

Activate this skill when:
- Planning new package releases
- Setting up package development workflow
- Creating package versions
- Managing beta releases
- Troubleshooting package installation issues
- Implementing CI/CD for packages
- Configuring CumulusCI automation
- Developing patch/hotfix strategy

Apply this lifecycle systematically for professional, maintainable managed packages that support customer success.