Overhaul Python package metadata and OpenDev URLs

Modernize our package metadata in the following ways:

* switch from description-file to long_description with the file
  attribute, and specify an explicit content type and encoding

* replace the home-page parameter with the newer general url one

* add specific labelled project links for improved navigation from
  PyPI's summary sidebar

* add commandline keyword to help folks searching

* use the specific license metadata in addition to the corresponding
  trove classifier for it

* make sure wheels when built also incorporate the LICENSE and
  AUTHORS files so that we're not distributing them without a copy
  of the license text

* stop flagging wheels as "universal" now that git-review no longer
  supports Python 2.7

* drop the old Sphinx integration config for PBR now that it's no
  longer needed

https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html

Also update old openstack.org URLs throughout contributor docs and
examples/comments to newer opendev.org counterparts. Remove the old
redundant HACKING.rst file as well as a lingering MANIFEST.in from
the times before PBR was a thing. Replace the CONTRIBUTING.rst with
a shorter one cribbed from bindep. Add the test profile to the one
entry in bindep.txt to make it more apparent that's not a runtime
dependency of git-review. Adjust some old "OpenStack, LLC."
copyrights as indicated by the foundation's "Legal Issues FAQ."

Change-Id: Ie45d4d73ba7b5a860f09cc4f1d849587761d846c

CONTRIBUTING.rst

@@ -1,38 +1,44 @@
-============================
+Contribution Overview
- Contributing to git-review
+=====================
-============================
 
-This tool is considered mostly feature-complete by its authors. It
+OpenDev's tools are hosted within the OpenDev collaboratory, and
-is meant to provide a simple, convenient tool for users of basic
+development for them uses workflows described in the OpenDev
-Gerrit change workflows. Contributions fixing bugs or regressions,
+Infrastructure Manual:
-maintaining support for newer Gerrit/Git releases and improving test
-coverage are welcome and encouraged. It is not, however, intended as
-an all-encompassing Gerrit client (there are plenty of other tools
-available supporting more advanced interactions), so proposed
-feature additions may make more sense implemented as complementary
-``git`` subcommands or similar related but separate projects.
 
-To get the latest code, see: https://git.openstack.org/cgit/openstack-infra/git-review
+http://docs.opendev.org/opendev/manual/developers.html
 
-Bugs are handled at: https://storyboard.openstack.org/#!/project/719
+Defect reporting and task tracking takes place here:
 
-Code reviews, as you might expect, are handled by gerrit at:
+https://storyboard.openstack.org/#!/project/opendev/git-review
-https://review.openstack.org
-Pull requests submitted through GitHub will be ignored.
 
-Use ``git review`` to submit patches (after creating a gerrit account
+Developing git-review
-that links to your launchpad account). Example::
+=====================
 
-    # Do your commits
+Either install `bindep` and run ``bindep test`` to check you have the needed
-    git review
+tools, or review ``bindep.txt`` by hand.
-    # Enter your username if prompted
 
-The code review process is documented at
+Running Tests
-https://docs.openstack.org/infra/manual/developers.html If that process is
+-------------
-not enough to get reviewers' attention then try these (in that order):
 
-1. Use git log and git blame to find "who last touched the file" and add
+The testing system is based on a combination of tox and testr. The canonical
-   them. Make sure they're still active on https://review.openstack.org
+approach to running tests is to simply run the command `tox`. This will
-2. Ping the #openstack-infra IRC channel, see developers.html above.
+create virtual environments, populate them with dependencies and run all of
-3. As a last resort, mailing-list at:
+the tests that OpenStack CI systems run. Behind the scenes, tox is running
-   http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra
+`testr run --parallel`, but is set up such that you can supply any additional
+testr arguments that are needed to tox. For example, you can run:
+`tox -- --analyze-isolation` to cause tox to tell testr to add
+--analyze-isolation to its argument list.
+
+It is also possible to run the tests inside of a virtual environment
+you have created, or it is possible that you have all of the dependencies
+installed locally already. If you'd like to go this route, the requirements
+are listed in requirements.txt and the requirements for testing are in
+test-requirements.txt. Installing them via pip, for instance, is simply::
+
+  pip install -r requirements.txt -r test-requirements.txt
+
+In you go this route, you can interact with the testr command directly.
+Running `testr run` will run the entire test suite. `testr run --parallel`
+will run it in parallel (this is the default incantation tox uses.) More
+information about testr can be found at:
+https://testrepository.readthedocs.io/en/latest/

HACKING.rst

@@ -1,314 +0,0 @@
-Hacking git-review
-==================
-
-Development of git-review is managed by OpenStack's Gerrit, which can be
-found at https://review.openstack.org/
-
-Instructions on submitting patches can be found at
-http://docs.openstack.org/infra/manual/developers.html#development-workflow
-
-git-review should, in general, not depend on a huge number of external
-libraries, so that installing it is a lightweight operation.
-
-OpenStack Style Commandments
-============================
-
-- Step 1: Read http://www.python.org/dev/peps/pep-0008/
-- Step 2: Read http://www.python.org/dev/peps/pep-0008/ again
-- Step 3: Read on
-
-
-General
--------
-- Put two newlines between top-level code (funcs, classes, etc)
-- Use only UNIX style newlines ("\n"), not Windows style ("\r\n")
-- Put one newline between methods in classes and anywhere else
-- Long lines should be wrapped in parentheses
-  in preference to using a backslash for line continuation.
-- Do not write "except:", use "except Exception:" at the very least
-- Include your name with TODOs as in "#TODO(termie)"
-- Do not shadow a built-in or reserved word. Example::
-
-    def list():
-        return [1, 2, 3]
-
-    mylist = list() # BAD, shadows `list` built-in
-
-    class Foo(object):
-        def list(self):
-            return [1, 2, 3]
-
-    mylist = Foo().list() # OKAY, does not shadow built-in
-
-- Use the "is not" operator when testing for unequal identities. Example::
-
-    if not X is Y:  # BAD, intended behavior is ambiguous
-        pass
-
-    if X is not Y:  # OKAY, intuitive
-        pass
-
-- Use the "not in" operator for evaluating membership in a collection. Example::
-
-    if not X in Y:  # BAD, intended behavior is ambiguous
-        pass
-
-    if X not in Y:  # OKAY, intuitive
-        pass
-
-    if not (X in Y or X in Z):  # OKAY, still better than all those 'not's
-        pass
-
-
-Imports
--------
-- Do not import objects, only modules (*)
-- Do not import more than one module per line (*)
-- Do not use wildcard ``*`` import (*)
-- Do not make relative imports
-- Do not make new nova.db imports in nova/virt/*
-- Order your imports by the full module path
-- Organize your imports according to the following template
-
-(*) exceptions are:
-
-- imports from ``migrate`` package
-- imports from ``sqlalchemy`` package
-- imports from ``nova.db.sqlalchemy.session`` module
-- imports from ``nova.db.sqlalchemy.migration.versioning_api`` package
-
-Example::
-
-  # vim: tabstop=4 shiftwidth=4 softtabstop=4
-  {{stdlib imports in human alphabetical order}}
-  \n
-  {{third-party lib imports in human alphabetical order}}
-  \n
-  {{nova imports in human alphabetical order}}
-  \n
-  \n
-  {{begin your code}}
-
-
-Human Alphabetical Order Examples
----------------------------------
-Example::
-
-  import httplib
-  import logging
-  import random
-  import StringIO
-  import time
-  import unittest
-
-  import eventlet
-  import webob.exc
-
-  import nova.api.ec2
-  from nova.api import openstack
-  from nova.auth import users
-  from nova.endpoint import cloud
-  import nova.flags
-  from nova import test
-
-
-Docstrings
-----------
-Example::
-
-  """A one line docstring looks like this and ends in a period."""
-
-
-  """A multi line docstring has a one-line summary, less than 80 characters.
-
-  Then a new paragraph after a newline that explains in more detail any
-  general information about the function, class or method. Example usages
-  are also great to have here if it is a complex class or function.
-
-  When writing the docstring for a class, an extra line should be placed
-  after the closing quotations. For more in-depth explanations for these
-  decisions see http://www.python.org/dev/peps/pep-0257/
-
-  If you are going to describe parameters and return values, use Sphinx, the
-  appropriate syntax is as follows.
-
-  :param foo: the foo parameter
-  :param bar: the bar parameter
-  :returns: return_type -- description of the return value
-  :returns: description of the return value
-  :raises: AttributeError, KeyError
-  """
-
-
-Dictionaries/Lists
-------------------
-If a dictionary (dict) or list object is longer than 80 characters, its items
-should be split with newlines. Embedded iterables should have their items
-indented. Additionally, the last item in the dictionary should have a trailing
-comma. This increases readability and simplifies future diffs.
-
-Example::
-
-  my_dictionary = {
-      "image": {
-          "name": "Just a Snapshot",
-          "size": 2749573,
-          "properties": {
-               "user_id": 12,
-               "arch": "x86_64",
-          },
-          "things": [
-              "thing_one",
-              "thing_two",
-          ],
-          "status": "ACTIVE",
-      },
-  }
-
-
-Calling Methods
----------------
-Calls to methods 80 characters or longer should format each argument with
-newlines. This is not a requirement, but a guideline::
-
-    unnecessarily_long_function_name('string one',
-                                     'string two',
-                                     kwarg1=constants.ACTIVE,
-                                     kwarg2=['a', 'b', 'c'])
-
-
-Rather than constructing parameters inline, it is better to break things up::
-
-    list_of_strings = [
-        'what_a_long_string',
-        'not as long',
-    ]
-
-    dict_of_numbers = {
-        'one': 1,
-        'two': 2,
-        'twenty four': 24,
-    }
-
-    object_one.call_a_method('string three',
-                             'string four',
-                             kwarg1=list_of_strings,
-                             kwarg2=dict_of_numbers)
-
-
-Internationalization (i18n) Strings
------------------------------------
-In order to support multiple languages, we have a mechanism to support
-automatic translations of exception and log strings.
-
-Example::
-
-    msg = _("An error occurred")
-    raise HTTPBadRequest(explanation=msg)
-
-If you have a variable to place within the string, first internationalize the
-template string then do the replacement.
-
-Example::
-
-    msg = _("Missing parameter: %s") % ("flavor",)
-    LOG.error(msg)
-
-If you have multiple variables to place in the string, use keyword parameters.
-This helps our translators reorder parameters when needed.
-
-Example::
-
-    msg = _("The server with id %(s_id)s has no key %(m_key)s")
-    LOG.error(msg % {"s_id": "1234", "m_key": "imageId"})
-
-
-Creating Unit Tests
--------------------
-For every new feature, unit tests should be created that both test and
-(implicitly) document the usage of said feature. If submitting a patch for a
-bug that had no unit test, a new passing unit test should be added. If a
-submitted bug fix does have a unit test, be sure to add a new one that fails
-without the patch and passes with the patch.
-
-For more information on creating unit tests and utilizing the testing
-infrastructure in OpenStack Nova, please read nova/tests/README.rst.
-
-
-Running Tests
--------------
-The testing system is based on a combination of tox and testr. The canonical
-approach to running tests is to simply run the command `tox`. This will
-create virtual environments, populate them with dependencies and run all of
-the tests that OpenStack CI systems run. Behind the scenes, tox is running
-`testr run --parallel`, but is set up such that you can supply any additional
-testr arguments that are needed to tox. For example, you can run:
-`tox -- --analyze-isolation` to cause tox to tell testr to add
---analyze-isolation to its argument list. Arguments past ``--`` are passed
-through to testr, for instance to run a single test::
-
-  tox -e py36 -- git_review.tests.test_unit.SomeClass.some_test
-
-It is also possible to run the tests inside of a virtual environment
-you have created, or it is possible that you have all of the dependencies
-installed locally already. In this case, you can interact with the testr
-command directly. Running `testr run` will run the entire test suite. `testr
-run --parallel` will run it in parallel (this is the default incantation tox
-uses.) More information about testr can be found at:
-http://wiki.openstack.org/testr
-
-
-openstack-common
-----------------
-
-A number of modules from openstack-common are imported into the project.
-
-These modules are "incubating" in openstack-common and are kept in sync
-with the help of openstack-common's update.py script. See:
-
-  http://wiki.openstack.org/CommonLibrary#Incubation
-
-The copy of the code should never be directly modified here. Please
-always update openstack-common first and then run the script to copy
-the changes across.
-
-OpenStack Trademark
--------------------
-
-OpenStack is a registered trademark of the OpenStack Foundation, and uses the
-following capitalization:
-
-   OpenStack
-
-
-Commit Messages
----------------
-Using a common format for commit messages will help keep our git history
-readable. Follow these guidelines:
-
-  First, provide a brief summary of 50 characters or less.  Summaries
-  of greater then 72 characters will be rejected by the gate.
-
-  The first line of the commit message should provide an accurate
-  description of the change, not just a reference to a bug or
-  blueprint. It must be followed by a single blank line.
-
-  If the change relates to a specific driver (libvirt, xenapi, qpid, etc...),
-  begin the first line of the commit message with the driver name, lowercased,
-  followed by a colon.
-
-  Following your brief summary, provide a more detailed description of
-  the patch, manually wrapping the text at 72 characters. This
-  description should provide enough detail that one does not have to
-  refer to external resources to determine its high-level functionality.
-
-  Once you use 'git review', two lines will be appended to the commit
-  message: a blank line followed by a 'Change-Id'. This is important
-  to correlate this commit with a specific review in Gerrit, and it
-  should not be modified.
-
-For further information on constructing high quality commit messages,
-and how to split up commits into a series of changes, consult the
-project wiki:
-
-   http://wiki.openstack.org/GitCommitMessages

MANIFEST.in

@@ -1,7 +0,0 @@
-include README.rst
-include LICENSE
-include AUTHORS
-include ChangeLog
-include HACKING.rst
-include git-review.1
-include tox.ini

README.rst

@@ -3,10 +3,10 @@ git-review
 
 A git command for submitting branches to Gerrit
 
-git-review is a tool that helps submitting git branches to gerrit for
+git-review is a tool that helps submitting Git branches to Gerrit for
 review.
 
 * Free software: Apache license
-* Documentation: http://docs.openstack.org/infra/git-review/
+* Documentation: http://docs.opendev.org/opendev/git-review
-* Source: https://git.openstack.org/cgit/openstack-infra/git-review
+* Source: https://opendev.org/opendev/git-review
 * Bugs: https://storyboard.openstack.org/#!/project/opendev/git-review

bindep.txt

@@ -1,5 +1,5 @@
-# This is a cross-platform list tracking distribution packages needed for install and tests;
+# This is a cross-platform list tracking distribution packages needed for
-# see http://docs.openstack.org/infra/bindep/ for additional information.
+# install and tests; see http://docs.opendev.org/opendev/bindep/ for additional
-
+# information.
-openjdk-8-jdk
 
+openjdk-8-jdk [test]

doc/source/installation.rst

@@ -51,9 +51,9 @@ section below.
 Example .gitreview file (used to upload for git-review itself)::
 
     [gerrit]
-    host=review.openstack.org
+    host=review.opendev.org
     port=29418
-    project=openstack-infra/git-review.git
+    project=opendev/git-review.git
     defaultbranch=master
 
 Required values: ``host``, ``project``

git-review.1

@@ -495,13 +495,14 @@ defaultbranch=master
 .Ed
 .Sh BUGS
 Bug reports can be submitted to
-.Lk https://launchpad.net/git\-review
+.Lk https://storyboard.openstack.org/#!/project/opendev/git\-review
 .Sh AUTHORS
 .Nm
 is maintained by
-.An "OpenStack, LLC"
+.An "OpenDev Contributors"
 .Pp
 This manpage has been enhanced by:
 .An "Antoine Musso" Aq hashar@free.fr
+.An "Jeremy Stanley" Aq fungi@yuggoth.org
 .An "Marcin Cieslak" Aq saper@saper.info
 .An "Pavel Sedlák" Aq psedlak@redhat.com

git_review/cmd.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-# Copyright (C) 2011-2020 OpenStack LLC.
+# Copyright OpenStack Foundation and OpenDev Contributors
 #
 # Licensed under the Apache License, Version 2.0 (the "License"); you may
 # not use this file except in compliance with the License.  You may obtain
@@ -45,7 +45,7 @@ DEFAULTS = dict(scheme='ssh', hostname=False, port=None, project=False,
                 branch='master', remote="gerrit", rebase="1",
                 track="0", usepushurl="0", notopic=False, branchauthor="name")
 COPYRIGHT = """\
-Copyright (C) 2011-2020 OpenStack LLC.
+Copyright OpenStack Foundation and OpenDev Contributors
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -1372,21 +1372,21 @@ class _DownloadFlag(argparse.Action):
     def __call__(self, parser, namespace, value, option_string=None):
         url = urlparse(value)
         # Turn URLs into change ids:
-        #   https://review.openstack.org/423436
+        #   https://review.opendev.org/423436
         # and
-        #   https://review.openstack.org/423436/
+        #   https://review.opendev.org/423436/
         # and
-        #   https://review.openstack.org/#/c/423436
+        #   https://review.opendev.org/#/c/423436
         # and
-        #   https://review.openstack.org/c/<project>/+/423436
+        #   https://review.opendev.org/c/<project>/+/423436
         # become
         #   "423436"
         # while
-        #   https://review.openstack.org/423436/1
+        #   https://review.opendev.org/423436/1
         # and
-        #   https://review.openstack.org/#/c/423436/1
+        #   https://review.opendev.org/#/c/423436/1
         # and
-        #   https://review.openstack.org/c/<project>/+/423436/1
+        #   https://review.opendev.org/c/<project>/+/423436/1
         # become
         #   "423436,1".
         #

git_review/tests/test_unit.py

@@ -393,42 +393,42 @@ class DownloadFlagUnitTest(testtools.TestCase):
     def test_parse_url(self):
         args = self.parser.parse_args(
             ['-d',
-             'https://review.openstack.org/12345']
+             'https://review.opendev.org/12345']
         )
         self.assertEqual('12345', args.cid)
 
     def test_parse_url_trailing_slash(self):
         args = self.parser.parse_args(
             ['-d',
-             'https://review.openstack.org/12345/']
+             'https://review.opendev.org/12345/']
         )
         self.assertEqual('12345', args.cid)
 
     def test_parse_url_with_update(self):
         args = self.parser.parse_args(
             ['-d',
-             'https://review.openstack.org/12345/2']
+             'https://review.opendev.org/12345/2']
         )
         self.assertEqual('12345,2', args.cid)
 
     def test_parse_url_with_hash(self):
         args = self.parser.parse_args(
             ['-d',
-             'https://review.openstack.org/#/c/12345']
+             'https://review.opendev.org/#/c/12345']
         )
         self.assertEqual('12345', args.cid)
 
     def test_parse_url_with_hash_and_update(self):
         args = self.parser.parse_args(
             ['-d',
-             'https://review.openstack.org/#/c/12345/1']
+             'https://review.opendev.org/#/c/12345/1']
         )
         self.assertEqual('12345,1', args.cid)
 
     def test_parse_polygerrit_url(self):
         args = self.parser.parse_args(
             ['-d',
-             'https://review.openstack.org/c/org/project/+/12345']
+             'https://review.opendev.org/c/org/project/+/12345']
         )
         self.assertEqual('12345', args.cid)
 
@@ -436,37 +436,36 @@ class DownloadFlagUnitTest(testtools.TestCase):
 class RepoUrlParsingTest(testtools.TestCase):
     """Test Git URL parsing"""
 
-    def test_ssh_openstack(self):
+    def test_ssh_opendev(self):
         self.assertEqual(
             cmd.parse_gerrit_ssh_params_from_git_url(
-                'ssh://someone@review.openstack.org:29418/x/y'),
+                'ssh://someone@review.opendev.org:29418/x/y'),
-            ('review.openstack.org', 'someone', '29418',
+            ('review.opendev.org', 'someone', '29418',
              'x/y'))
 
     def test_ssh_no_user_no_port(self):
         self.assertEqual(
             cmd.parse_gerrit_ssh_params_from_git_url(
-                'ssh://review.openstack.org/openstack-infra/git-review'),
+                'ssh://review.opendev.org/opendev/git-review'),
-            ('review.openstack.org', None, None,
+            ('review.opendev.org', None, None, 'opendev/git-review'))
-             'openstack-infra/git-review'))
 
     def test_ssh_at_sign(self):
         self.assertEqual(
             cmd.parse_gerrit_ssh_params_from_git_url(
-                'ssh://someone@example.org@review.openstack.org:29418/x/y'),
+                'ssh://someone@example.org@review.opendev.org:29418/x/y'),
-            ('review.openstack.org', 'someone@example.org', '29418',
+            ('review.opendev.org', 'someone@example.org', '29418',
              'x/y'))
 
     def test_ssh_at_signs_excessive(self):
         self.assertEqual(
             cmd.parse_gerrit_ssh_params_from_git_url(
-                'ssh://x@y@example.org@review.openstack.org:29418/x/y'),
+                'ssh://x@y@example.org@review.opendev.org:29418/x/y'),
-            ('review.openstack.org', 'x@y@example.org', '29418',
+            ('review.opendev.org', 'x@y@example.org', '29418',
              'x/y'))
 
     def test_ssh_at_sign_escaped(self):
         self.assertEqual(
             cmd.parse_gerrit_ssh_params_from_git_url(
-                r'ssh://someone%40example.org@review.openstack.org:29418/x/y'),
+                r'ssh://someone%40example.org@review.opendev.org:29418/x/y'),
-            ('review.openstack.org', r'someone%40example.org', '29418',
+            ('review.opendev.org', r'someone%40example.org', '29418',
              'x/y'))

setup.cfg

@@ -1,9 +1,30 @@
 [metadata]
 name = git-review
 summary = Tool to submit code to Gerrit
-description-file = README.rst
+long_description = file: README.rst
-license = Apache License (2.0)
+long_description_content_type = text/x-rst; charset=UTF-8
+author = OpenDev Contributors
+author-email = service-discuss@lists.opendev.org
+url = http://docs.opendev.org/opendev/git-review
+project_urls =
+    Browse Source = https://opendev.org/opendev/git-review
+    Bug Reporting = https://storyboard.openstack.org/#!/project/opendev/git-review
+    Documentation = https://docs.opendev.org/opendev/git-review
+    Git Clone URL = https://opendev.org/opendev/git-review
+    License Texts = https://opendev.org/opendev/git-review/src/branch/master/LICENSE
+    Release Notes = https://docs.opendev.org/opendev/git-review/latest/releasenotes.html
+keywords = git gerrit review commandline
+license = Apache License, Version 2.0
+license_files =
+    AUTHORS
+    LICENSE
 classifiers =
+    Development Status :: 5 - Production/Stable
+    Environment :: Console
+    Intended Audience :: Developers
+    Intended Audience :: Information Technology
+    License :: OSI Approved :: Apache Software License
+    Operating System :: OS Independent
     Programming Language :: Python :: 3
     Programming Language :: Python :: 3.5
     Programming Language :: Python :: 3.6
@@ -11,18 +32,7 @@ classifiers =
     Programming Language :: Python :: 3.8
     Programming Language :: Python :: 3.9
     Programming Language :: Python
-    Development Status :: 5 - Production/Stable
+    Topic :: Utilities
-    Environment :: Console
-    Environment :: OpenStack
-    Intended Audience :: Developers
-    Intended Audience :: Information Technology
-    License :: OSI Approved :: Apache Software License
-    Operating System :: OS Independent
-keywords = git gerrit review
-author = OpenStack
-author-email = openstack-infra@lists.openstack.org
-home-page = http://docs.openstack.org/infra/git-review/
-project-url = http://docs.openstack.org/infra/
 python-requires = >= 3.5
 
 [files]
@@ -33,14 +43,6 @@ packages =
 console_scripts =
     git-review = git_review.cmd:main
 
-[wheel]
-universal = 1
-
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-
 [pbr]
 manpages =
     git-review.1

tox.ini

@@ -4,8 +4,7 @@ ignore_basepython_conflict = true
 
 [testenv]
 basepython = python3
-# See "testing behind a proxy"
+# See "testing behind a proxy" https://review.opendev.org/624496
-# @ https://review.openstack.org/#/q/I764ed51314c8e2d0572d1f0
 passenv =
   http_proxy
   https_proxy