docs: def upgrade(refresh=True, dist_upgrade=False, **kwargs):
      '''
      .. versionchanged:: 2015.8.12,2016.3.3,2016.11.0
          On minions running systemd>=205, `systemd-run(1)`_ is now used to
          isolate commands which modify installed packages from the
          ``salt-minion`` daemon's control group. This is done to keep systemd
          from killing any apt-get/dpkg commands spawned by Salt when the
          ``salt-minion`` service is restarted. (see ``KillMode`` in the
          `systemd.kill(5)`_ manpage for more information). If desired, usage of
          `systemd-run(1)`_ can be suppressed by setting a :mod:`config option
          <salt.modules.config.get>` called ``systemd.scope``, with a value of
          ``False`` (no quotes).
  
      .. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html
      .. _`systemd.kill(5)`: https://www.freedesktop.org/software/systemd/man/systemd.kill.html
  
      Upgrades all packages via ``apt-get upgrade`` or ``apt-get dist-upgrade``
      if  ``dist_upgrade`` is ``True``.
  
      Returns a dictionary containing the changes:
  
      .. code-block:: python
  
          {'<package>':  {'old': '<old-version>',
                          'new': '<new-version>'}}
  
      dist_upgrade
          Whether to perform the upgrade using dist-upgrade vs upgrade.  Default
          is to use upgrade.
  
          .. versionadded:: 2014.7.0
  
      cache_valid_time
  
          .. versionadded:: 2016.11.0
  
          Skip refreshing the package database if refresh has already occurred within
          <value> seconds
  
      download_only
          Only download the packages, don't unpack or install them
  
          .. versionadded:: 2018.3.0
  
      force_conf_new
          Always install the new version of any configuration files.
  
          .. versionadded:: 2015.8.0
  
      CLI Example:
  
      .. code-block:: bash
  
          salt '*' pkg.upgrade
      '''
      cache_valid_time = kwargs.pop('cache_valid_time', 0)
      if salt.utils.data.is_true(refresh):
          refresh_db(cache_valid_time)
  
      old = list_pkgs()
      if 'force_conf_new' in kwargs and kwargs['force_conf_new']:
          force_conf = '--force-confnew'
      else:
          force_conf = '--force-confold'
      cmd = ['apt-get', '-q', '-y', '-o', 'DPkg::Options::={0}'.format(force_conf),
             '-o', 'DPkg::Options::=--force-confdef']
  
      if kwargs.get('force_yes', False):
          cmd.append('--force-yes')
      if kwargs.get('skip_verify', False):
          cmd.append('--allow-unauthenticated')
      if kwargs.get('download_only', False):
          cmd.append('--download-only')
  
      cmd.append('dist-upgrade' if dist_upgrade else 'upgrade')
      result = _call_apt(cmd, env=DPKG_ENV_VARS.copy())
      __context__.pop('pkg.list_pkgs', None)
      new = list_pkgs()
      ret = salt.utils.data.compare_dicts(old, new)
  
      if result['retcode'] != 0:
          raise CommandExecutionError(
              'Problem encountered upgrading packages',
              info={'changes': ret, 'result': result}
          )
  
      return ret