Skip to content

Instantly share code, notes, and snippets.

@shilman

shilman/RELEASE.md

Last active June 22, 2017 22:41
Download ZIP

Revisions

  1. shilman revised this gist Jun 22, 2017. 1 changed file with 2 additions and 1 deletion.
    3 changes: 2 additions & 1 deletion RELEASE.md
    View file
    Original file line number Diff line number Diff line change
    @@ -69,8 +69,9 @@ should have killer features that reward users for upgrading, and should not be u
    - Once it's implemented, the discussion may be occur on the PR (ex: https://github.com/storybooks/storybook/issues/151)
    - If people disagree on an implementation and it can't be resolved in discussion, they may issue alternative PR's with different ideas
    - Ultimately the maintainers will reach a concensus before merging the changes. There is no set process for this, but we're all adults.
    - Since MINOR features are released in alpha before they are fully released, new issues may be created by end users, etc.
    - For MAJOR infrastructural changes, the discussion may take place over time, in gists like this one, issues, slack discussions, etc.
    - Once the breaking changes have been reduced to an actual implementation, it looks pretty much like a feature release (only with higher stakes and a longer stabilization process).
    - Once the breaking changes have been reduced to an actual implementation, it looks pretty much like a feature release (only with higher stakes and probably a longer stabilization process).

    ## FAQ's

  2. shilman revised this gist Jun 22, 2017. 1 changed file with 7 additions and 1 deletion.
    8 changes: 7 additions & 1 deletion RELEASE.md
    View file
    Original file line number Diff line number Diff line change
    @@ -70,4 +70,10 @@ should have killer features that reward users for upgrading, and should not be u
    - If people disagree on an implementation and it can't be resolved in discussion, they may issue alternative PR's with different ideas
    - Ultimately the maintainers will reach a concensus before merging the changes. There is no set process for this, but we're all adults.
    - For MAJOR infrastructural changes, the discussion may take place over time, in gists like this one, issues, slack discussions, etc.
    - Once the breaking changes have been reduced to an actual implementation, it looks pretty much like a feature release (only with higher stakes and a longer stabilization process).
    - Once the breaking changes have been reduced to an actual implementation, it looks pretty much like a feature release (only with higher stakes and a longer stabilization process).

    ## FAQ's

    #### How does my PR get merged?
    - For PATCH PR's, any maintainer can review, test, approve, and merge it.
    - For MINOR/MAJOR PR's, once a maintainer reviews, tests, and approves it, s/he should clear it with the other maintainers before merging it into the release branch.
  3. shilman revised this gist Jun 22, 2017. 1 changed file with 11 additions and 0 deletions.
    11 changes: 11 additions & 0 deletions RELEASE.md
    View file
    Original file line number Diff line number Diff line change
    @@ -60,3 +60,14 @@ agreed upon by the maintainers and validated in backwards-compatible feature rel
    thoroughly vetted, we deprecate the old way and give some time for people to upgrade to the new way. Finally MAJOR releases
    should have killer features that reward users for upgrading, and should not be used to scratch our own architectural itches
    -- unless those itches are really killing development in some meaningful way.

    ## Discussion

    - For PATCH changes, all discussion can occur in issue/PR comments (and random slack chat as needed).
    - For MINOR feature changes, there are multiple stages of discussion:
    - The feature may be discussed in an issue before it is implemented (ex: https://github.com/storybooks/storybook/issues/151)
    - Once it's implemented, the discussion may be occur on the PR (ex: https://github.com/storybooks/storybook/issues/151)
    - If people disagree on an implementation and it can't be resolved in discussion, they may issue alternative PR's with different ideas
    - Ultimately the maintainers will reach a concensus before merging the changes. There is no set process for this, but we're all adults.
    - For MAJOR infrastructural changes, the discussion may take place over time, in gists like this one, issues, slack discussions, etc.
    - Once the breaking changes have been reduced to an actual implementation, it looks pretty much like a feature release (only with higher stakes and a longer stabilization process).
  4. shilman revised this gist Jun 22, 2017. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions RELEASE.md
    View file
    Original file line number Diff line number Diff line change
    @@ -45,13 +45,13 @@ deserves more attention:
    2. They often have architectural implications for the entire Storybook ecosystem, so should be discussed thoroughly before release. Doing `alpha` releases allow us to test in the community without necessarily achieving agreement. For example, currently `Vue` support is in `alpha`, although it contains potentially controversial changes to addons.
    3. They often deserve proper marketing treatment (blog posts, release announcement, podcast, etc.)

    Therefore we mere these into a release branch of the form `release/MAJOR.MINOR` and we create preview
    Therefore we merge these into a release branch of the form `release/MAJOR.MINOR` and we create preview
    releases and get them tested by the community before merging those branches into `master`.

    > NOTE: it is possible to edit the `base` branch in a PR, so we can expect users to issue PRs to `master`, but as maintainers as we see feature releases we should set them to merge into the appropriate release branch.
    In general we should release 2-3 headline features per minor release for marketing purposes. Each headline feature
    should get its own blog post on the Storybook medium pub, and the release itself should also get a blog post.
    should get its own blog post on the Storybook medium publication, and the release itself should also get a blog post.

    ## MAJOR releases

  5. shilman created this gist Jun 22, 2017.
    62 changes: 62 additions & 0 deletions RELEASE.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,62 @@
    # Storybook Release Proposal

    A Storybook release process based on [Semver](http://semver.org/). In short:
    1. merge bugfix PRs directly into master automatically release (~daily)
    2. merge feature and breaking PRs into a release branch (e.g. `release/3.2`) and release features in groups along with a marketing push after a preview period (~monthly)

    ## Motivation

    During the Storybook 3.x transition we've undergone a series of growing pains as we've opened up the development process. We've had questions about:

    1. how to adhere to semver?
    2. how to do marketing releases (while adhering to semver)?
    3. how to introduce significant new features (e.g. vue support, story hierarchy)?
    4. how to converge on key design decisions (e.g. new addons API)?
    6. how to schedule releases?
    5. how to maintain quality/stability through the process?

    This proposal attempts to address all of these concerns in one shot.

    ## Semver

    [Semver](http://semver.org/) dictates three types of release:

    1. MAJOR version when you make incompatible API changes,
    2. MINOR version when you add functionality in a backwards-compatible manner, and
    3. PATCH version when you make backwards-compatible bug fixes.

    We'll do our best to adhere to Semver, but won't be religious about it. In
    particular, we may occasionally release small bits of new functionality in PATCH
    releases. We'll try our best to restrict breaking changes to MAJOR releases.

    ## PATCH releases

    Every bugfix should go out as soon as we've verified the fix, and based on the
    current rate of contribution, we should be issuing PATCH releases multiple times per week.
    Soon we'll automate the process so that a release will go out every time a PR is
    merged into `master`, and we've already laid most of the groundwork for this.

    ## MINOR releases

    Every new feature, particularly significant ones (e.g. Vue support, deep hierarchy for stories)
    deserves more attention:

    1. They should be well-tested by the community before we release.
    2. They often have architectural implications for the entire Storybook ecosystem, so should be discussed thoroughly before release. Doing `alpha` releases allow us to test in the community without necessarily achieving agreement. For example, currently `Vue` support is in `alpha`, although it contains potentially controversial changes to addons.
    3. They often deserve proper marketing treatment (blog posts, release announcement, podcast, etc.)

    Therefore we mere these into a release branch of the form `release/MAJOR.MINOR` and we create preview
    releases and get them tested by the community before merging those branches into `master`.

    > NOTE: it is possible to edit the `base` branch in a PR, so we can expect users to issue PRs to `master`, but as maintainers as we see feature releases we should set them to merge into the appropriate release branch.
    In general we should release 2-3 headline features per minor release for marketing purposes. Each headline feature
    should get its own blog post on the Storybook medium pub, and the release itself should also get a blog post.

    ## MAJOR releases

    We should avoid major releases, and should try to do these at most 1-2x per year. Ideally each breaking change would have been
    agreed upon by the maintainers and validated in backwards-compatible feature releases. At some point once a change has been
    thoroughly vetted, we deprecate the old way and give some time for people to upgrade to the new way. Finally MAJOR releases
    should have killer features that reward users for upgrading, and should not be used to scratch our own architectural itches
    -- unless those itches are really killing development in some meaningful way.