magit-push: only push to branch.b.merge when pushing to branch.b.remote

The branch specified by the former is only meaningful when pushing to
the remote specified by the latter.  When pushing to another remote
and the remote branch is not specified explicitly then pusing to the
remote branch with the same name as the local branch being pushed is
much more reasonable than pushing to branch.b.merge which could be
anything.  This is also how "git push <remote> <branch>" behaves.
always respect value of magit-set-upstream-on-push

Previously both branch.<name>.remote and branch.<name>.merge where set
under certain conditions ignoring the value of magit-set-upstream-on-push:
when both branch.<name>.remote and remote.origin.url are unset
branch.<name>.remote was always set.  When additionally no prefix argument
is used branch.<name>.merge was also set ignoring the value of
magit-set-upstream-on-push.
magit-builtin-completing-read: handle REQUIRE-MATCH safely

completing-read does allow the user to exit with null input, leaving
it to the caller to handle that case.  Possible options would be to
use some default value or raise an error.

Since magit-builtin-completing-read is a convenience wrapper for
completing-read it seems reasonable to do the latter here so that not
every caller of magit-completing-read has to do this on it's own.

A similar change is not required for magit-iswitchb-completing-read
and magit-ido-completing-read; they already don't allow the user to
exit with a null value.
magit-read-remote: require that an existing remote is selected

All current uses of magit-read-remote actually require a remote to
be returned as the behaviour of nil being returned is not defined.
E.g. magit-push would try to push to a remote with the name "nil".

It would be better to give magit-read-remote a REQUIRE-MATCH argument
but since all callers expect a match this is not strictly unnecessary
at the moment.  Also some other magit-read-* functions could benefit
from a similar change.
magit-push: ensure we are pushing to a branch

Do this by always using the full ref instead of just the name for
the remote branch.  Without this we could end pushing to some other
non-branch ref if no branch by the specified name exists remotely
but some other ref by that name does.
magit-push: set branch.<name>.merge correctly

The backward compatibility hack that ensured that branch.<name>.merge
was set even when using an old version of git used the wrong local
variable.  In many cases that variable contains the correct value but
this does not have to be the case.  More specifically it always used
the same ref as the ref of the local branch.  When the user selected
another branch name that obviously is not correct.  So this kludge for
older git versions could actually harm users of recent versions.
magit-push: do not use magit-get-remote to get the branch-remote

The meaning of "branch-remote" is "the remote configured for branch"
but if no remote is configured magit-get-remote might return "origin"
instead.  This is wrong here because we later use the value of
branch-remote to determine if we we should push to branch.<name>.merge
or just <name>.

So this ensures that we do the right thing when branch.<name>.merge is
set but branch.<name>.remote is not.
magit-push: update doc-string to reflect recent changes

Actually this new doc-string - for the bigger part - would have been
correct even before these changes since most of them are actually
bugfixes.  So the new doc-string wouldn't have been more wrong than
the old one :-)

No longer say that in certain cases something "hairy" is done when
that behaviour is well defined in git-push(1) and also reasonable.
Instead explicitly say what is done (pushing to the remote branch
with the same name as the local branch) and under what conditions.

I think the new doc-string is much easier to understand.  For better
readability I removed the instructions how prefix arguments are used;
the user has to get that knowledge elsewhere.  Not every command that
supports prefix arguments documents that basics of their use; why
should this one be different?
magit-push: set branch.<name>.merge when -u is in magit-custom-options

When --set-upstream is set through magit-key-mode use the same
backward compatibility hack to ensure branch.<name>.merge is set
even when using an old git version as is used when --set-upstream
is used due to the value of the magit-set-upstream-on-push option.