Releasing Packages

README.md

Short story about what problems the code solves

How to use and contribute

License

Read "On Open Sourcing Libraries" goo.gl/uNTt7K

CHANGELOG.md

gitk 1.3.0..master

List relevant additions and fixes

List BC breaks prominently

Tag Releases

Often

Before breaking BC

It's easy: git tag 1.3.0

Semantic Versioning

semver.org

MAJOR . MINOR . PATCH

1 . 2 . 3

MAJOR . MINOR . PATCH

Breaks           Features           Fixes  

Dev
  -> 0.1.0

Fixes
  -> 0.1.1

Breaking changes
  -> 0.2.0

First stable
  -> 1.0.0

Fixes
  -> 1.0.1

Fixes
  -> 1.0.2

New features
  -> 1.1.0

Breaking changes
  -> 2.0.0

Version Constraints

Exact Match

1.0.0   1.2.3-beta2   dev-master

Range

1.0.*   2.*

Unbounded Range (BAD)

>=1.0

Operators

, = AND    | = OR

Next Significant Release

~1.2   =   >=1.2.0,<2.0.0

Next Significant Release

~1.2.3   =   >=1.2.3,<1.3.0

Libraries should use ~

~

Composer Stabilities

Stabilities

dev -> alpha -> beta -> RC -> stable

Tags

2.0.2 -> stable

2.0.0-beta2 -> beta

Branches

2.0 -> 2.0.x-dev (dev)

master -> dev-master (dev)

lala-feature -> dev-lala-feature (dev)

Resolution Conflicts

Overly Strict Requirements

// composer.json
{
    "require": {
        "cool/alice": "~1.3",
        "lazy/bob": "~1.2"
    }
}

// dependencies
{
    "name": "cool/alice",
    "require": {
        "monolog/monolog": "~1.6"
    }
}
{
    "name": "lazy/bob",
    "require": {
        "monolog/monolog": ">=1.3,<1.5"
    }
}
            

Overly Strict Requirements

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for lazy/bob ~1.2 -> satisfiable by lazy/bob[1.4.0].
    - Installation request for cool/alice ~1.3 -> satisfiable by cool/alice[1.3.0].
    - lazy/bob 1.4.0 requires monolog/monolog >=1.3,<1.5 -> satisfiable by monolog/monolog[1.3.0, 1.3.1, 1.4.0, 1.4.1].
    - cool/alice 1.3.0 requires monolog/monolog ~1.6 -> satisfiable by monolog/monolog[1.6.0, 1.7.0].
    - Can only install one of: monolog/monolog[1.6.0, 1.3.0].
    - Can only install one of: monolog/monolog[1.6.0, 1.3.1].
    - Conclusion: don't install monolog/monolog 1.4.1
    - Conclusion: don't install monolog/monolog 1.7.0
    - Conclusion: don't install monolog/monolog 1.4.0
    - Conclusion: don't install monolog/monolog 1.6.0
            

Stability Resolution

// composer.json
{
    "minimum-stability": "beta",
    "require": {
        "monolog/monolog": "1.*",
        "symfony/symfony": "~2.4",
        "bad/package": "dev-master"
    }
}

// dependencies
{
    "name": "bad/package",
    "require": {
        "monolog/monolog": "dev-master",
    }
}
            

Stability Resolution

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for bad/package dev-master -> satisfiable by bad/package[dev-master].
    - bad/package dev-master requires monolog/monolog dev-master -> no matching package found.
            

Forced to require monolog in dev version

Stability Resolution

// composer.json
{
    "minimum-stability": "beta",
    "require": {
        "monolog/monolog": "1.*@dev",
        "symfony/symfony": "~2.4",
        "bad/package": "dev-master"
    }
}

// dependencies
{
    "name": "bad/package",
    "require": {
        "monolog/monolog": "dev-master",
    }
}
            

Stability Resolution

// monolog
{
    "name": "monolog/monolog",
    "extra": {
        "branch-alias": {
            "dev-master": "1.7.x-dev"
        }
    }
}
            

Stability Resolution

- Installing monolog/monolog (dev-master 5ad421d)
  Cloning 5ad421d6a1d5d7066a45b617e5164d309c4e2852
            

Stability Resolution

Six months later... monolog 2.0!

Stability Resolution

// monolog
{
    "name": "monolog/monolog",
    "extra": {
        "branch-alias": {
            "dev-master": "2.0.x-dev"
        }
    }
}
            

Stability Resolution

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for monolog/monolog 1.*@dev -> satisfiable by monolog/monolog[1.7.0].
    - Installation request for bad/package dev-master -> satisfiable by bad/package[dev-master].
    - bad/package dev-master requires monolog/monolog dev-master -> satisfiable by monolog/monolog[dev-master].
    - Can only install one of: monolog/monolog[1.7.0, dev-master].
            

Forced to require monolog 2.*@dev or dev-master.

master might have broken bad/package and our project.

The Lock File

composer.lock

Commit it

Thank you.

Questions?

jordi@nelm.io

@seldaek

slides.seld.be