From 7c1e3af8e09595f6e1815ef4081a9d052a286d2a Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Mon, 27 Jun 2016 03:13:37 +0200 Subject: [PATCH] add internal docs about making releases --- build/controllers/ReleaseController.php | 53 ++++++++++++++++-------- docs/internals/README.md | 4 +- docs/internals/release.md | 73 +++++++++++++++++++++++++++++++++ docs/internals/versions.md | 2 +- 4 files changed, 113 insertions(+), 19 deletions(-) create mode 100644 docs/internals/release.md diff --git a/build/controllers/ReleaseController.php b/build/controllers/ReleaseController.php index 8560b86..4951ce3 100644 --- a/build/controllers/ReleaseController.php +++ b/build/controllers/ReleaseController.php @@ -56,6 +56,10 @@ class ReleaseController extends Controller * @var bool whether to fetch latest tags. */ public $update = false; + /** + * @var string override the default version. e.g. for major or patch releases. + */ + public $version; public function options($actionID) @@ -63,6 +67,7 @@ class ReleaseController extends Controller $options = ['basePath']; if ($actionID === 'release') { $options[] = 'dryRun'; + $options[] = 'version'; } elseif ($actionID === 'info') { $options[] = 'update'; } @@ -190,7 +195,17 @@ class ReleaseController extends Controller $this->validateWhat($what); $versions = $this->getCurrentVersions($what); - $newVersions = $this->getNextVersions($versions, self::PATCH);// TODO add support for minor + + if ($this->version !== null) { + // if a version is explicitly given + $newVersions = []; + foreach($versions as $k => $v) { + $newVersions[$k] = $this->version; + } + } else { + // otherwise get next patch or minor + $newVersions = $this->getNextVersions($versions, self::PATCH); + } $this->stdout("You are about to prepare a new release for the following things:\n\n"); $this->printWhat($what, $newVersions, $versions); @@ -363,8 +378,10 @@ class ReleaseController extends Controller $this->stdout($h = "Preparing framework release version $version", Console::BOLD); $this->stdout("\n" . str_repeat('-', strlen($h)) . "\n\n", Console::BOLD); - $this->runGit('git checkout master', $frameworkPath); // TODO add compatibility for other release branches - $this->runGit('git pull', $frameworkPath); // TODO add compatibility for other release branches + if (!$this->confirm('Make sure you are on the right branch for this release and that it tracks the correct remote branch! Continue?')) { + exit(1); + } + $this->runGit('git pull', $frameworkPath); // checks @@ -415,8 +432,8 @@ class ReleaseController extends Controller $this->stdout("\n\nHint: if you decide 'no' for any of the following, the command will not be executed. You may manually run them later if needed. E.g. try the release locally without pushing it.\n\n"); $this->runGit("git commit -a -m \"release version $version\"", $frameworkPath); - $this->runGit("git tag -a $version -m\"version $version\"", $frameworkPath); - $this->runGit("git push origin master", $frameworkPath); + $this->runGit("git tag -a $version -m \"version $version\"", $frameworkPath); + $this->runGit("git push", $frameworkPath); $this->runGit("git push --tags", $frameworkPath); $this->stdout("\n\n"); @@ -467,7 +484,7 @@ class ReleaseController extends Controller $this->runGit("git diff --color", $frameworkPath); $this->stdout("\n\n"); $this->runGit("git commit -a -m \"prepare for next release\"", $frameworkPath); - $this->runGit("git push origin master", $frameworkPath); + $this->runGit("git push", $frameworkPath); $this->stdout("\n\nDONE!", Console::FG_YELLOW, Console::BOLD); @@ -492,8 +509,10 @@ class ReleaseController extends Controller $this->stdout($h = "Preparing release for application $name version $version", Console::BOLD); $this->stdout("\n" . str_repeat('-', strlen($h)) . "\n\n", Console::BOLD); - $this->runGit('git checkout master', $path); // TODO add compatibility for other release branches - $this->runGit('git pull', $path); // TODO add compatibility for other release branches + if (!$this->confirm('Make sure you are on the right branch for this release and that it tracks the correct remote branch! Continue?')) { + exit(1); + } + $this->runGit('git pull', $path); // adjustments @@ -526,8 +545,8 @@ class ReleaseController extends Controller $this->stdout("\n\nHint: if you decide 'no' for any of the following, the command will not be executed. You may manually run them later if needed. E.g. try the release locally without pushing it.\n\n"); $this->runGit("git commit -a -m \"release version $version\"", $path); - $this->runGit("git tag -a $version -m\"version $version\"", $path); - $this->runGit("git push origin master", $path); + $this->runGit("git tag -a $version -m \"version $version\"", $path); + $this->runGit("git push", $path); $this->runGit("git push --tags", $path); $this->stdout("\n\n"); @@ -551,7 +570,7 @@ class ReleaseController extends Controller $this->runGit("git diff --color", $path); $this->stdout("\n\n"); $this->runGit("git commit -a -m \"prepare for next release\"", $path); - $this->runGit("git push origin master", $path); + $this->runGit("git push", $path); $this->stdout("\n\nDONE!", Console::FG_YELLOW, Console::BOLD); @@ -606,8 +625,10 @@ class ReleaseController extends Controller $this->stdout($h = "Preparing release for extension $name version $version", Console::BOLD); $this->stdout("\n" . str_repeat('-', strlen($h)) . "\n\n", Console::BOLD); - $this->runGit('git checkout master', $path); // TODO add compatibility for other release branches - $this->runGit('git pull', $path); // TODO add compatibility for other release branches + if (!$this->confirm('Make sure you are on the right branch for this release and that it tracks the correct remote branch! Continue?')) { + exit(1); + } + $this->runGit('git pull', $path); // adjustments @@ -640,8 +661,8 @@ class ReleaseController extends Controller $this->stdout("\n\nHint: if you decide 'no' for any of the following, the command will not be executed. You may manually run them later if needed. E.g. try the release locally without pushing it.\n\n"); $this->runGit("git commit -a -m \"release version $version\"", $path); - $this->runGit("git tag -a $version -m\"version $version\"", $path); - $this->runGit("git push origin master", $path); + $this->runGit("git tag -a $version -m \"version $version\"", $path); + $this->runGit("git push", $path); $this->runGit("git push --tags", $path); $this->stdout("\n\n"); @@ -664,7 +685,7 @@ class ReleaseController extends Controller $this->runGit("git diff --color", $path); $this->stdout("\n\n"); $this->runGit("git commit -a -m \"prepare for next release\"", $path); - $this->runGit("git push origin master", $path); + $this->runGit("git push", $path); $this->stdout("\n\nDONE!", Console::FG_YELLOW, Console::BOLD); diff --git a/docs/internals/README.md b/docs/internals/README.md index c4c639e..8c7e4fd 100644 --- a/docs/internals/README.md +++ b/docs/internals/README.md @@ -13,7 +13,7 @@ Contributor Guidelines - [Yii2 View Code Style](view-code-style.md) -Dokumentation +Documentation ------------- - [Translation Status](translation-status.md) - which documents are ready for translation. @@ -33,7 +33,7 @@ Versioning and Release - [Project Organization](project-organization.md) - [Yii Versioning](versions.md) - +- [Releasing a new version](release.md) Misc ---- diff --git a/docs/internals/release.md b/docs/internals/release.md new file mode 100644 index 0000000..da1b180 --- /dev/null +++ b/docs/internals/release.md @@ -0,0 +1,73 @@ +Releasing a new version +======================= + +The list of steps needed to make a release of the framework has grown over time and became +hard to manage manually, so we have created a command line tool to ensure no step is forgotten. + +Release steps overview +---------------------- + +- ... + +The release command +------------------- + +These steps are automated in the [release console command](../../build/controllers/ReleaseController.php) +which is included in the framework development repository. + +The release command can be invoked using the Yii application contained in the `build` directory of +the framework: + + ./build/build help release # run this in framework repo root + +> Info: You can run the command with the `--dryRun` option to see what it would do. Using this option, +> no changes will be made and no commits or tags will be created or pushed. + +### Requirements + +The release command depends on the development environment introduced in +the [Git Workflow Document](git-workflow.md#extensions), i.e. the application +templates must be located under `/apps/` and extensions must be located under `/extensions/`. +This structure is preferably created using the `dev/app` command. + +### Version overview + +To get an overview over the versions of framework and extensions, you can run + + ./build/build release/info + +You may run it with `--update` to fetch tags for all repos to get the newest information. + +### Make a release + +Making a framework release includes the following commands (apps are always released together with the framework): + + ./build release framework + ./build release app-basic + ./build release app-advanced + +Making an extension release includes only one command (e.g. for redis): + + ./build release redis + +The default release command will release a new minor version from the currently checked out branch. +To release another version thatn the default, you have to specify it using the `--version` option, e.g. +`--version=2.1.0`, or `--version=2.1.0-beta`. + + +#### Release a new major version e.g. 2.1.0 + +Releasing a new major version includes a branch change as described in the +[versioning policy](versions.md). +The following describes an example of releasing version `2.1.0` which has been +developed on the `2.1` branch derived from `master`. `master` has contained the `2.0.x` versions +before. + +- create a new branch `2.0` from `master` +- ensure composer.json does not contain a branch alias on this branch anymore. +- merge necessary changes from `master` to `2.1` +- point `master` to the lastest commit on `2.1` +- delete `2.1` branch + +Now check out `master` and run the release command with the `--version=2.1.0` option. + diff --git a/docs/internals/versions.md b/docs/internals/versions.md index eb7e70b..2b2961f 100644 --- a/docs/internals/versions.md +++ b/docs/internals/versions.md @@ -77,7 +77,7 @@ The following image shows an illustration of the branches on changing commit his ## Releases -Both Yii2 Framework and official extension projects follow the above versioning and branching policies. +Both Yii2 Framework and official extension projects follow the above versioning and branching policies. Framework and official extension projects are released independently of each other, i.e. version number mismatch between framework and extension is expected. The Application Templates are always released together with the framework.