diff options
| -rw-r--r-- | doc/intro.cli | 93 |
1 files changed, 72 insertions, 21 deletions
diff --git a/doc/intro.cli b/doc/intro.cli index 5ee8a14..bb1b753 100644 --- a/doc/intro.cli +++ b/doc/intro.cli @@ -1277,7 +1277,7 @@ Just like with changes to dependency information, \c{status} has detected that a new (snapshot) version of our project is available for synchronization. \N|Another way to view the project's version (which works even if we are -not using \c{bdep}) is with the build system's \c{info} operation: +not using \c{bdep}) is with the build system's \c{info} meta-operation: \ $ b info @@ -1318,8 +1318,8 @@ discussed earlier, you can simply run the build system to update your project and things will get automatically synchronized if necessary.| Ok, time for our first release. Let's start with \c{0.1.0-a.1}. Unlike -snapshots, for pre-releases as well as final releases we have to update the -version in the \c{manifest} file manually: +snapshots, for pre-releases as well as final releases we have to change the +version in the \c{manifest} file: \ version: 0.1.0-a.1 @@ -1357,19 +1357,61 @@ $ git push Notice also that when specifying a snapshot version in \c{manifest} we use the special \cb{z} snapshot value (for example, \c{0.1.0-a.1.z}) which is recognized and automatically replaced by \c{build2} with, in case of \c{git}, -a commit timestamp and id (refer to \l{b#module-version \c{version} Module} -for details). +the current commit timestamp and id (refer to \l{b#module-version \c{version} +Module} for details). + +While not particularly complicated, performing the release steps manually is +both tedious and error-prone. Instead, this process can be automated with the +\l{bdep-release(1)} command. Specifically, in its default mode, this command +will update the version in the \c{manifest} file, commit and tag this change, +open the next development cycle (again, by changing \c{manifest} and +committing), and, finally, if \c{--push} is specified, push everything to the +remote. So, instead of the above manual steps, we could have simply run: + +\ +$ bdep release --alpha --push +releasing: + package: hello + current: 0.1.0-a.0.z + release: 0.1.0-a.1 + open: 0.1.0-a.1.z + commit: yes + tag: v0.1.0-a.1 + push: origin/master +continue? [y/n] y +[master 82a7e65] Release version 0.1.0-a.1 +[master e6cf3c0] Change version to 0.1.0-a.1.z +To github.com:john-doe/hello.git + 26ec5c9..e6cf3c0 master -> master + * [new tag] v0.1.0-a.1 -> v0.1.0-a.1 +\ + +\N|The \c{release} command has a number of alternative modes, such as for +releasing a package revision, as well as a number of options that control +which version will be released and which version will be opened. See +\l{bdep-release(1)} for details.| Publishing the final release to the version control repository is exactly the -same. This time, however, let's also see how we can publish it to an -archive-based repository. The first step is again to change the version, -commit, tag, and push: +same. This time, however, let's see how we can also publish it to an +archive-based repository. The first step is again to make the release, which +we will do with the help of the \c{release} command. Except now we will delay +opening the next development cycle by passing \c{--no-open} (there is also no +\c{--alpha} since this is the final release): \ -$ edit manifest # change 'version: 0.1.0' -$ git commit -a -m \"Release version 0.1.0\" -$ git tag -a v0.1.0 -m \"Tag version 0.1.0\" -$ git push --follow-tags +$ bdep release --no-open --push +releasing: + package: hello + current: 0.1.0-a.1.z + release: 0.1.0 + commit: yes + tag: v0.1.0 + push: origin/master +continue? [y/n] y +[master 00ed45a] Release version 0.1.0 +To github.com:john-doe/hello.git + 5d5094c..00ed45a master -> master + * [new tag] v0.1.0 -> v0.1.0 \ To publish our project to an archive-based repository we use the @@ -1418,12 +1460,21 @@ that package submissions to \c{cppget.org} are public and permanent and cannot be removed under any circumstances. Finally, we also shouldn't forget to increment the version for the next -development cycle: +development cycle. For that we can use the \c{--open} mode of the \c{release} +command. For example: \ -$ edit manifest # change 'version: 0.2.0-a.0.z' -$ git commit -a -m \"Change version to 0.2.0-a.0.z\" -$ git push +$ bdep release --open --push +opening: + package: hello + current: 0.1.0 + open: 0.2.0-a.0.z + commit: yes + push: origin/master +continue? [y/n] y +[master ace2f6e] Change version to 0.2.0-a.0.z +To github.com:john-doe/hello.git + 00ed45a..ace2f6e master -> master \ \N|One sticky point of continuous versioning is choosing the next version. @@ -1434,11 +1485,11 @@ versioning. But we can never jump backwards. For example, we can start with \c{0.2.0-a.0} but if we later realize that this will actually be a new major release, we can easily change it to -\c{1.0.0-a.0}. As a result, the general recommendation is to start -conservatively by either incrementing the patch or the minor version -component. The recommended strategy is to increment the minor component and, -if required, release patch versions from a separate branch (created by -branching off from the release commit). +\c{1.0.0-a.0}. As a result, the general guideline is to start conservatively +by either incrementing the patch or the minor version component. And the +recommended strategy is to increment the minor component and, if required, +release patch versions from a separate branch (created by branching off from +the release commit). This is the default behavior of the \c{release} command. Note also that you don't have to make any pre-releases if you don't need them. While during development you would still keep the version as \c{X.Y.Z-a.0}, at |