From 319953d5aba3fed42a72bcef8070d45e17702ced Mon Sep 17 00:00:00 2001 From: Jeremy Stanley Date: Fri, 26 Feb 2021 20:35:19 +0000 Subject: [PATCH] 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 | 66 +++---- HACKING.rst | 314 ---------------------------------- MANIFEST.in | 7 - README.rst | 6 +- bindep.txt | 8 +- doc/source/installation.rst | 4 +- git-review.1 | 5 +- git_review/cmd.py | 18 +- git_review/tests/test_unit.py | 35 ++-- setup.cfg | 46 ++--- tox.ini | 3 +- 11 files changed, 99 insertions(+), 413 deletions(-) delete mode 100644 HACKING.rst delete mode 100644 MANIFEST.in diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0285bc8c..9b43ec73 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,38 +1,44 @@ -============================ - Contributing to git-review -============================ +Contribution Overview +===================== -This tool is considered mostly feature-complete by its authors. It -is meant to provide a simple, convenient tool for users of basic -Gerrit change workflows. Contributions fixing bugs or regressions, -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. +OpenDev's tools are hosted within the OpenDev collaboratory, and +development for them uses workflows described in the OpenDev +Infrastructure Manual: -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://review.openstack.org -Pull requests submitted through GitHub will be ignored. +https://storyboard.openstack.org/#!/project/opendev/git-review -Use ``git review`` to submit patches (after creating a gerrit account -that links to your launchpad account). Example:: +Developing git-review +===================== - # Do your commits - git review - # Enter your username if prompted +Either install `bindep` and run ``bindep test`` to check you have the needed +tools, or review ``bindep.txt`` by hand. -The code review process is documented at -https://docs.openstack.org/infra/manual/developers.html If that process is -not enough to get reviewers' attention then try these (in that order): +Running Tests +------------- -1. Use git log and git blame to find "who last touched the file" and add - them. Make sure they're still active on https://review.openstack.org -2. Ping the #openstack-infra IRC channel, see developers.html above. -3. As a last resort, mailing-list at: - http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra +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. + +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/ diff --git a/HACKING.rst b/HACKING.rst deleted file mode 100644 index d18b9ca9..00000000 --- a/HACKING.rst +++ /dev/null @@ -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 diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index 21636ab4..00000000 --- a/MANIFEST.in +++ /dev/null @@ -1,7 +0,0 @@ -include README.rst -include LICENSE -include AUTHORS -include ChangeLog -include HACKING.rst -include git-review.1 -include tox.ini diff --git a/README.rst b/README.rst index e79a14ec..9ef7efc7 100644 --- a/README.rst +++ b/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/ -* Source: https://git.openstack.org/cgit/openstack-infra/git-review +* Documentation: http://docs.opendev.org/opendev/git-review +* Source: https://opendev.org/opendev/git-review * Bugs: https://storyboard.openstack.org/#!/project/opendev/git-review diff --git a/bindep.txt b/bindep.txt index 099230f8..ef605c8b 100644 --- a/bindep.txt +++ b/bindep.txt @@ -1,5 +1,5 @@ -# This is a cross-platform list tracking distribution packages needed for install and tests; -# see http://docs.openstack.org/infra/bindep/ for additional information. - -openjdk-8-jdk +# This is a cross-platform list tracking distribution packages needed for +# install and tests; see http://docs.opendev.org/opendev/bindep/ for additional +# information. +openjdk-8-jdk [test] diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 0d5b9a7a..32fbf64b 100644 --- a/doc/source/installation.rst +++ b/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`` diff --git a/git-review.1 b/git-review.1 index 1fba1227..aca526fb 100644 --- a/git-review.1 +++ b/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 diff --git a/git_review/cmd.py b/git_review/cmd.py index b86cfdff..4ae2ede1 100644 --- a/git_review/cmd.py +++ b/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//+/423436 + # https://review.opendev.org/c//+/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//+/423436/1 + # https://review.opendev.org/c//+/423436/1 # become # "423436,1". # diff --git a/git_review/tests/test_unit.py b/git_review/tests/test_unit.py index 9e201536..7dc0c0ec 100644 --- a/git_review/tests/test_unit.py +++ b/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'), - ('review.openstack.org', 'someone', '29418', + 'ssh://someone@review.opendev.org:29418/x/y'), + ('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'), - ('review.openstack.org', None, None, - 'openstack-infra/git-review')) + 'ssh://review.opendev.org/opendev/git-review'), + ('review.opendev.org', None, None, 'opendev/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'), - ('review.openstack.org', 'someone@example.org', '29418', + 'ssh://someone@example.org@review.opendev.org:29418/x/y'), + ('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'), - ('review.openstack.org', 'x@y@example.org', '29418', + 'ssh://x@y@example.org@review.opendev.org:29418/x/y'), + ('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'), - ('review.openstack.org', r'someone%40example.org', '29418', + r'ssh://someone%40example.org@review.opendev.org:29418/x/y'), + ('review.opendev.org', r'someone%40example.org', '29418', 'x/y')) diff --git a/setup.cfg b/setup.cfg index ae88ab73..fdaef4a2 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,9 +1,30 @@ [metadata] name = git-review summary = Tool to submit code to Gerrit -description-file = README.rst -license = Apache License (2.0) +long_description = file: README.rst +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 - 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/ + Topic :: Utilities 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 diff --git a/tox.ini b/tox.ini index e7bf4410..0152d7bc 100644 --- a/tox.ini +++ b/tox.ini @@ -4,8 +4,7 @@ ignore_basepython_conflict = true [testenv] basepython = python3 -# See "testing behind a proxy" -# @ https://review.openstack.org/#/q/I764ed51314c8e2d0572d1f0 +# See "testing behind a proxy" https://review.opendev.org/624496 passenv = http_proxy https_proxy