GitHub Releases
- You need to have Git and you need to have the Hub tool installed already.
From the dev branch, type:
$ git checkout 000000-dev
$ phing release-rc # Prepares a new RC release and moves you to that branch.
$ phing full-build-all # When you're ready to begin the build.From this point on, when building in this branch, the project_version is locked to the feature branch name; i.e., feature/16xxxx-RC in the branch name results in project_version=16xxxx-RC without fail. This allows you to build and rebuild, without inadvertently deviating from the intended use of this branch; i.e., to prepare an RC release matching the branch name.
A typical workflow might include several iterations of these commands while you are tuning things in and preparing the RC release. It's fine to build and rebuild as many times as you need to.
# ... change something in the release/16xxxx-RC branch.
$ phing full-build-all # Rebuild, w/ version locked onto release branch.
$ git add --all # Stage changes and commit.
$ git commit -m 'Tweaking RC release.'$ git add --all # Last commit before release; i.e., if any changes exist at this point, commit & push them.
$ git commit -m 'Finalizing RC release.' # i.e., Final commit before doing the release.
$ git push # Push changes to the remote.
$ phing release-rc # While on the RC release branch.In short, running the command a second time against a release branch of the same type (i.e., an RC branch) results in the release being finalized. This includes tagging the release, uploading distros to GitHub, etc.
A formal release can occur based on the dev branch or based on any existing release branch of a different type; e.g., basing it on a previous RC release, which is what I'll show in this example.
From an existing RC release branch, type:
$ git checkout release/16xxxx-RC
$ phing release # Prepares a new formal release and moves you to that branch.
# You will now be on branch: feature/%y%m%d (for the current day).
$ phing full-build-all # When you're ready to begin the build.From this point on, when building in this branch, the project_version is locked to the feature branch name; i.e., feature/16xxxx in the branch name results in project_version=16xxxx without fail. This allows you to build and rebuild, without inadvertently deviating from the intended use of this branch; i.e., to prepare a formal release matching the version in the branch name.
A typical workflow might include several iterations of these commands while you are tuning things in and preparing the release. It's fine to build and rebuild as many times as you need to.
# ... changed something in the release/16xxxx branch.
$ phing full-build-all # Rebuild, w/ version locked onto release branch.
$ git add --all # Stage changes and commit.
$ git commit -m 'Tweaking release.'$ git add --all # Last commit before release; i.e., if any changes exist at this point, commit & push them.
$ git commit -m 'Finalizing release.' # i.e., Final commit before doing the release.
$ git push # Push changes to the remote.
$ phing release # While on the release branch.In short, running the command a second time against a release branch of the same type (i.e., a formal release branch) results in the release being finalized. This includes tagging the release, uploading distros to GitHub, etc.
I am beginning to prefer the version format %y%m%d.%now instead of just %y%m%d. This makes it far easier to do multiple releases in the same day, and used in conjunction with these new release tools, it works very well. If you'd like to migrate from %y%m%d to %y%m%d.%now, change the string in your .build.props file and the release tools will automatically use that new format. Note that %now represents the number of seconds in the current day.
Whenever you work on the changelog for an upcoming release, you can use a special replacement code: $v. Here is a quick example of a changelog for an upcoming release, where the version is not given, but instead replaced automatically whenever you run $ phing release or $ phing release-rc and then do a build.
# $v
- An example changelog entry.
- Another example changelog entry.
= $v = (this format works also).
- An example changelog entry.
- Another example changelog entry.
And here is the workflow that can assist you:
$ phing release-rc # Or: phing release
$ phing full-build-allUpon running $ phing full-build-all from a release branch (RC or otherwise) $v becomes vXXXXXX (whatever the version for that release might be, depending on when you're doing the release.
If the first line in your CHANGELOG.md is the heading for an RC release from the past, that changelog heading is automatically updated when doing another RC or formal release. It doesn't need to contain $v, it is simply assumed that the last changelog heading was for a previous RC, which means it should be updated to reflect the version of your formal release, or of a subsequent RC release.
# vXXXXXX-RC
- An example changelog entry.
- Another example changelog entry.
= vXXXXXX-RC = (this format works also).
- An example changelog entry.
- Another example changelog entry.
Upon running $ phing full-build-all from a release branch (RC or otherwise) vXXXXXX-RC (whatever version it was) is updated to reflect the version that you're currently working to release. Again, this only occurs whenever the first line in your CHANGELOG.md file is for an RC release.
- It knows how to create
release/branches. - It knows how to create annotated git release tags for you.
- It knows how to upload the
.zip,.tar.gz, and a possible.pharfile to GitHub. - It knows how to collect the changelog entries and attach those to your GitHub release.
- It knows how to flag an RC release on GitHub as a pre-release automatically.
- It knows that a Pro release should always be posted as a Draft only and not made public.
- It knows how to automatically do the lite variation release also.
- It knows how to present you with URLs (when it's done) that lead to the GitHub release(s).
- and a few other things too, seen in responses you receive when performing various tasks.