Better wording for 'part'

[jalanb]

When trying out bumpversion for the first time, I found the error message to be distinctly unhelpful

$ bumpversion
usage: bumpversion [-h] [--config-file FILE] [--parse REGEX] [--serialize FORMAT] [--current-version VERSION] [--dry-run]
                   [--new-version VERSION] [--commit | --no-commit] [--tag | --no-tag] [--tag-name TAG_NAME] [--message COMMIT_MSG]
                   part [file [file ...]]
bumpversion: error: too few arguments

Which arguments does it want?

Oh, I see, buried in the middle of that verbiage the word "part" is not surrounded by brackets, nor preceded by dashes. Guess it must be looking for a "part" then. So, why didn't it say that, instead of arguments?

Anyway, what's a "part"? Lets try the help

$ bumpversion -h | grep part
Traceback (most recent call last):
  File "/Users/jab/bin/bumpversion", line 7, in <module>
    main()
  File "/usr/local/lib/python2.7/site-packages/bumpversion/__init__.py", line 301, in main
    args = parser3.parse_args(remaining_argv)
  File "/usr/local/lib/python2.7/argparse.py", line 1678, in parse_args
    args, argv = self.parse_known_args(args, namespace)
  File "/usr/local/lib/python2.7/argparse.py", line 1710, in parse_known_args
    namespace, args = self._parse_known_args(args, namespace)
  File "/usr/local/lib/python2.7/argparse.py", line 1916, in _parse_known_args
    start_index = consume_optional(start_index)
  File "/usr/local/lib/python2.7/argparse.py", line 1856, in consume_optional
    take_action(action, args, option_string)
  File "/usr/local/lib/python2.7/argparse.py", line 1784, in take_action
    action(self, namespace, argument_values, option_string)
  File "/usr/local/lib/python2.7/argparse.py", line 993, in __call__
    parser.print_help()
  File "/usr/local/lib/python2.7/argparse.py", line 2303, in print_help
    self._print_message(self.format_help(), file)
  File "/usr/local/lib/python2.7/argparse.py", line 2317, in _print_message
    file.write(message)
UnicodeEncodeError: 'ascii' codec can't encode character u'\u2192' in position 1630: ordinal not in range(128)

Not very helpful! Guess I'll have to leave out the grep then.

$ bumpversion -h
usage: bumpversion [-h] [--config-file FILE] [--parse REGEX] [--serialize FORMAT] [--current-version VERSION] [--dry-run]
                   [--new-version VERSION] [--commit | --no-commit] [--tag | --no-tag] [--tag-name TAG_NAME] [--message COMMIT_MSG]
                   part [file [file ...]]

Bumps version strings

positional arguments:
  part                  Part of the version to be bumped.
  file                  Files to change (default: [u'docs/conf.py', u'docs/index.rst'])

optional arguments:
  -h, --help            show this help message and exit
  --config-file FILE    Config file to read most of the variables from (default: .bumpversion.cfg)
  --parse REGEX         Regex parsing the version string (default: (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+))
  --serialize FORMAT    How to format what is parsed back to a version (default: {major}.{minor}.{patch})
  --current-version VERSION
                        Version that needs to be updated (default: 0.0.2)
  --dry-run, -n         Don't write any files, just pretend. (default: False)
  --new-version VERSION
                        New version that should be in the files (default: 0.0.2)
  --commit              Commit to version control (default: True)
  --no-commit           Do not commit to version control
  --tag                 Create a tag in version control (default: True)
  --no-tag              Do not create a tag in version control
  --tag-name TAG_NAME   Tag name (only works with --tag) (default: v{new_version})
  --message COMMIT_MSG, -m COMMIT_MSG
                        Commit message (default: Bump version: {current_version} → {new_version})

Even more verbiage, in the middle of which is

  part                  Part of the version to be bumped.

Not exactly the most helpful help ever. In fact, given that the command is called "bumpversion" and the missing argument is called "part" I would opine that "Part of the version to be bumped" actually says nothing at all.

OK, let's try the website, where we find

part

Part of the version to increase.

Valid values include those given in the --serialize / --parse option.

But I didn't use the --serialize / --parse option. And they are "options", so I don't have to use them. What's the default?

Further down on the web page we find
--serialize / serialize =

default: "{major}.{minor}.{patch}"

Not sure what syntax that is - does that mean I have to use 3 parts, or 3 parts to make one part, or that I can change it to use 3 parts, or ..., or what?

All told - that is such an obscure way of saying what the basic way of using the command is as to be grossly unhelpful.

I would suggest that the usage message should mention "parts", not "arguments". And the default allowable arguments of major/minor/patch should be mentioned in the usage message. They should also be, at least, available for reading on the command line, not just on the website.

Finally, and less obviously, I would suggest that part be made optional, and the simplest avaialble command should be

$ bumpversion

which should bump the patch level

[peritus]

First: Thank you for writing this down, especially usability problems like this are hard to come by because I can't look every user over the shoulder and hear them thinking!

About: bumpversion: error: too few arguments: That's auto-generated by argparse, because no command line argument was given (and part is among many others an argument). You're right, this can only be caused by not giving a "part" at the moment. I should probably catch this explicitly and show a nicer error message, before handing things off to argparse.

In the standard configuration, a part is "one of major, minor, patch", however that list is configurable so it might be anything else.

You're right "part" may be an unfortunate name, and it's very well up for discussion. "level" might be better, but I don't think that's to the point. Why is it so hard finding a name for this ?

About your suggestion making "part" optional: That was the default behavior in bumpversion < 0.3, and I made it so because bumping versions is something explicit that you do conciously and I want users to make an explicit choice which part of the version should be bumped.

[peritus]

Closing this until someone (maybe me?) comes up with a better name. I'm very open to suggestions!