Add preliminary initial scenario

1 files changed, 129 insertions, 0 deletions

diff --git a/bumper.yarn b/bumper.yarn
new file mode 100644
index 0000000..b29286a
--- /dev/null
+++ b/bumper.yarn
@@ -0,0 +1,129 @@
+---
+title: Bump version numbers when releasing
+author: Lars Wirzenius
+version: git version
+...
+
+
+# Introduction
+
+Bumper is a small utility for updating version numbers when making a
+release of a software project. It updates the version number in the
+various locations in which it is stored in the source tree, creates a
+git tag for indicating the release, then updates the source tree again
+with a version number that indicates an unreleased version.
+
+# Assumptions about the source tree
+
+Bumper makes several assumptions about the source tree, to keep things
+simpler. Here's a list:
+
+* The source tree is stored in git. No other version control systems
+  are supported, sorry, but that's just because git is the only thing
+  the author uses now.
+
+* The project is in Python. Again, this is just because that's what
+  the author uses.
+
+* The code gets its version numbers from two variables in a Python
+  module that contains nothing else. The variables are `__version__`
+  and `__version_info__`. Bumper will overwrite the file with new
+  values when it runs, and commit its version to git.
+
+* It's OK for Bumper to make several commits and a tag in the git
+  repository.
+
+
+# Using Bumper
+
+In the examples below, we'll use Bumper on a fairly typical Python
+project called `foo`, and we'll make a release 3.2 of it.
+
+    SCENARIO release a project
+
+The Foo project consists of a main program, which uses a little Python
+package where all the real code is, and where the version number is
+also stored.
+
+    GIVEN Python project foo, version controlled by git
+    AND a file foolib/version.py in foo containing 
+    ... "__version__ = '0.0'\n__version_info__ = (0, 0)\n"
+
+We run Bumper, and it does several things.
+
+    WHEN user runs "bumper 3.2 foolib/version.py" in the foo directory
+    THEN git repository foo has tag foo-3.2
+    AND in foo, tag foo-3.2, foolib/version.py contains
+    ... "__version__ = "3.2"\n__version_info__ = (3, 2)\n"
+    AND file foolib/version.py in foo contains
+    ... "__version__ = "3.2"\n__version_info__ = (3, 2)\n"
+
+
+# Appendix: Scenario step implementations
+
+This chapter provides executable implementations of the various
+scenario steps, making this manual an automated [yarn][] test suite
+for Bumper.
+
+[yarn]: http://liw.fi/cmdtest/
+
+    IMPLEMENTS GIVEN Python project (\S+), version controlled by git
+    import os, cliapp, yarnstep
+    project = yarnstep.get_next_match()
+    dirname = yarnstep.datadir(project)
+    yarnstep.write_file(os.path.join(dirname, 'setup.py'), '''
+    from distutils.core import setup
+    setup(name='{project}')
+    '''.format(project=project))
+    cliapp.runcmd(['git', 'init', dirname])
+
+    IMPLEMENTS GIVEN a file (\S+) in (\S+) containing "(.*)"
+    import os, cliapp, yarnstep
+    filename = yarnstep.get_next_match()
+    dirname = yarnstep.get_next_match_as_datadir_path()
+    data = yarnstep.get_next_match()
+    yarnstep.write_file(
+        os.path.join(dirname, filename),
+        yarnstep.unescape_backslashes(data))
+    cliapp.runcmd(['git', 'add', filename], cwd=dirname)
+    cliapp.runcmd(
+        ['git', 'commit', '-m', 'Add {}'.format(filename)],
+        cwd=dirname)
+
+    IMPLEMENTS WHEN user runs "bumper (\S+) (\S+)" in the (\S+) directory
+    import cliapp, yarnstep
+    version = yarnstep.get_next_match()
+    filename = yarnstep.get_next_match()
+    dirname = yarnstep.get_next_match_as_datadir_path()
+    bin = yarnstep.srcdir('bumper')
+    cliapp.runcmd([bin, version, filename], cwd=dirname)
+
+    IMPLEMENTS THEN file (\S+) in (\S+) contains "(.*)"
+    import os, yarnstep
+    filename = yarnstep.get_next_match()
+    dirname = yarnstep.get_next_match_as_datadir_path()
+    wanted_data_escaped = yarnstep.get_next_match()
+    wanted_data = yarnstep.unescape_backslashes(wanted_data_escaped)
+    actual_data = yarnstep.cat(os.path.join(dirname, filename))
+    assert wanted_data == actual_data
+
+    IMPLEMENTS THEN in (\S+), tag (\S+), (\S+) contains "(.*)"
+    import cliapp, yarnstep
+    dirname = yarnstep.get_next_match_as_datadir_path()
+    tag = yarnstep.get_next_match()
+    filename = yarnstep.get_next_match()
+    wanted_data_escaped = yarnstep.get_next_match()
+    wanted_data = yarnstep.unescape_backslashes(wanted_data_escaped)
+    actual_data = cliapp.runcmd(
+        ['git', 'cat-file', 'blob', '{}:{}'.format(tag, filename)],
+        cwd=dirname)
+    print 'wanted:', repr(wanted_data)
+    print 'actual:', repr(actual_data)
+    assert wanted_data == actual_data
+
+    IMPLEMENTS THEN git repository (\S+) has tag (\S+)
+    import cliapp, yarnstep
+    dirname = yarnstep.get_next_match_as_datadir_path()
+    tagname = yarnstep.get_next_match()
+    output = cliapp.runcmd(['git', 'show', tagname], cwd=dirname)
+    assert output.startswith('tag ' + tagname)