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

   git checkout -b feature/new-capability
   

2. Create scratch org

   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

   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

   sf project retrieve start --source-dir force-app
   

5. Run tests continuously

   sf apex run test --test-level RunLocalTests --result-format human
   

6. Commit changes

   git add .
   git commit -m "Add new capability"
   

7. Push to remote

   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

   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

   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...",
    "MyPackage@1.2.0-1": "04t..."
  }
}

Validate Package

Verify package installation and functionality before beta release.

Validation Checklist:

1. Install in fresh scratch org

   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:

# 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

   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

   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

   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

   sf package version promote --package "MyPackage@1.2.1-1"
   

6. Merge hotfix back

   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 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.