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:

# 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:

{
  "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:

// 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:

@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:

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:

# 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:

{
  "packageAliases": {
    "MyPackage": "0Ho...",
    "[email protected]": "04t..."
  }
}

Validate Package

Verify package installation and functionality before beta release.

Validation Checklist:

1. Install in fresh scratch org bash sf package install --package "[email protected]" --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:

# Promote package version from beta to released
sf package version promote --package "[email protected]"

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 "[email protected]"

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:

pip install cumulusci
cci project init

Configure cumulusci.yml:

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:

cci flow run dev_org --org dev

Run tests:

cci task run run_tests --org dev

Build and release:

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:

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

# 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 [email protected]

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

# List versions
sf package version list --package MyPackage

Version Number Guide

Lifecycle Phase Summary

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.