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:

•Design & Planning - Define requirements, architecture, and release strategy
•Development - Build features in scratch orgs with version control
•Testing - Validate functionality, integration, and upgrade paths
•Packaging - Create versioned package artifacts
•Beta Release - Deploy to test environments and gather feedback
•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:

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

•
Break down features into metadata components
- •Objects, fields, relationships
- •Apex classes, triggers, test classes
- •Lightning Web Components
- •Flows, permission sets, custom metadata
•
Sequence development work
- •Build foundational components first (domain model, services)
- •Add business logic and integrations
- •Implement UI last
•
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:

•
Create feature branch
bash
```
git checkout -b feature/new-capability
```

•

Create scratch org

bash

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

•

Push source to scratch org

bash

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

•
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
```

•

Run tests continuously

bash

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

•

Commit changes

bash

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

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

•
Setup test data representing real scenarios
- •Multiple related objects
- •Permission set assignments
- •Custom metadata configuration
•
Execute complete workflows
- •User actions through UI
- •API calls with full payloads
- •Scheduled batch jobs
•
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:

•Fresh installation - New customer with no prior version
•Upgrade from previous version - Existing customer updating
•Skipped version upgrade - Customer jumping multiple versions
•Data migration - Schema changes requiring data transformation

Upgrade Test Process:

•
Install previous package version in scratch org
bash
```
sf package install --package 04t... --wait 20
```
•
Setup customer-like configuration
- •Create custom fields on package objects (if allowed)
- •Configure custom metadata
- •Insert test data

•

Upgrade to new version

bash

sf package install --package 04t... --wait 20 --upgrade-type mixed

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

code

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:

•

Install in fresh scratch org

bash

sf package install --package "MyPackage@1.2.0-1" --wait 20

•
Verify all components installed
- •Check Setup > Installed Packages
- •Review component list in package details
•
Run smoke tests
- •Execute critical user workflows
- •Validate no permission errors
- •Check debug logs for exceptions
•
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:

•
Create beta package version (done in Phase 4)

•

Share beta installation link

code

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t...

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

•
Setup feedback mechanisms
- •GitHub Issues for bug reports
- •Survey for feature feedback
- •Scheduled check-in calls
•
Monitor beta installations
- •Track installation success/failures
- •Review error logs from beta orgs
- •Monitor support cases
•
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:

•
Update AppExchange listing (if applicable)
- •New version number
- •Updated release notes
- •New screenshots/videos
•
Publish release notes
- •New features
- •Bug fixes
- •Known issues
- •Upgrade instructions
•
Notify customers
- •Email announcement
- •In-app notifications
- •AppExchange listing update

•

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:

•
Track installations
- •Monitor installation success rate
- •Identify common installation errors
•
Review support cases
- •Categorize issues by severity
- •Identify patterns in bug reports
•
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:

•
Create hotfix branch from release tag
bash
```
git checkout -b hotfix/1.2.1 v1.2.0
```
•
Develop fix in scratch org
- •Minimal code changes
- •Focus only on bug fix
- •Comprehensive test coverage

•

Create patch version

bash

sf package version create \
  --package "MyPackage" \
  --version-number "1.2.1.NEXT" \
  --skip-validation

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

•

Release patch

bash

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

•

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:

•Lint and validate - Check code quality
•Build package version - Create package artifact
•Run unit tests - Validate code coverage
•Integration tests - End-to-end validation
•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:

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

Version Management Mistakes

Common errors:

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

Release Process Issues

Watch out for:

•Incomplete release notes - Document all changes
•Missing migration scripts - Provide upgrade guidance
•No beta testing - Validate with real users first
•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.