In argparse.rst, while documenting ArgumentParser.add_subparsers, ``prog`` is described on line 1630 as:
  usage information that will be displayed with sub-command help,
  by default the name of the program and any positional arguments 
  before the subparser argument

This is confusing since ``prog`` is actually a very small prefix of the usage message.  Describing this parameter as "name of the program" or event "name of the program with sub-commands" would be more clear.

That sounds likes reasonable improvement.  Would you like to submit a PR?

For ArgumentParser, prog is defined as:

    prog - The name of the program (default: sys.argv[0])

The comment in the `add_subparsers` method is:

       # prog defaults to the usage message of this parser, skipping
       # optional arguments and with no "usage:" prefix

        if kwargs.get('prog') is None:
            formatter = self._get_formatter()
            positionals = self._get_positional_actions()
            groups = self._mutually_exclusive_groups
            formatter.add_usage(self.usage, positionals, groups, '')
            kwargs['prog'] = formatter.format_help().strip()

and this keyword is saved as the action `self._prog_prefix.

Later in `add_parser` this is amended with:

     kwargs['prog'] = '%s %s' % (self._prog_prefix, name)

The intent is to provide the string required to run a particular subparser (sub-command), the `prog` of the main, positionals, and the subcommand. (It doesn't handle all 'required' arguments correctly.) 

The programmer has three places where they can customize this 'prog'.

So the default 'prog' as the 'add_subarsers' level is indeed just the main 'prog' plus 'positionals'.  The default 'prog' display with the subcommand usage add the subcommand's name.

It's a complicated sequence, but I think the description for the 'add_subparsers' 'prog' is enough.

Raymond, I would love to submit the PR if we reach a consensus on what the new message should be.  I'm a bit out of touch with how things work these days.  Is Github the best place to submit the PR?

Paul, very good digging!  Reading the coding and running a few examples, I understand that the ``prog`` of the subparser is always the name of the main program with the name of the subcommand *unless* a usage string is supplied, in which case it overrides prog.  I suspect that the intent is to favour the programmer supplied usage string and that copying the usage string in the prog of the subparser is an implementation detail.   I think we can reword the documentation to describe the expected behavior with more emphasis on the common cases.

Yannick: the PRs are submitted via github; you can find more detail on contributions workflow / process here:

https://devguide.python.org/