aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2019-01-14 14:55:16 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2019-01-14 14:55:16 +0200
commit75b866d44e6858bfb03df4c3065ac3984449aa6a (patch)
tree2d2490c88784b9b173c833c6448b216d9463c6ad
parent8d461cbd91e766f56ae84ed802582b944f54f6c3 (diff)
Show bdep-release usage in introduction
-rw-r--r--doc/intro.cli93
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