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:

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:

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

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

Create scratch org

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

Push source to scratch org

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
```
sf project retrieve start --source-dir force-app
```

Run tests continuously

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

Commit changes

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

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:

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:

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

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

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:

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

Install in fresh scratch org

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

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:

# 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

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

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

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

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:

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

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

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.

package-development-lifecycle

SKILL.md