From 63da3ebb54606d8c70a1804fbd39a4a998bc01aa Mon Sep 17 00:00:00 2001 From: Brian Rosmaita Date: Tue, 9 Feb 2021 18:52:08 -0500 Subject: [PATCH] Format as a Cinder-related OpenStack project - rearrange docs and add doc/requirements.txt - add releasenotes directory and reno setup files - update some requirements - add lower-constraints - update tox.ini - minor changes for doc8 and pep8 - add .zuul.yaml Technical debt: the tox 'pylint' testenv doesn't work; see comments in tox.ini Change-Id: I35e4dc1b9af91741176784886a84c55fbd4cd11c --- .gitignore | 14 ++ .gitreview | 4 + .travis.yml | 17 -- .zuul.yaml | 26 +++ CONTRIBUTING.rst | 130 ++------------- HACKING.rst | 58 +++++++ HISTORY.rst | 8 - LICENSE | 182 +++++++++++++++++++-- Makefile | 88 ---------- README.rst | 25 +-- babel.cfg | 1 + doc/requirements.txt | 7 + doc/source/_extra/.placeholder | 0 doc/source/_static/.placeholder | 0 doc/source/conf.py | 17 +- doc/source/contributing.rst | 1 - doc/source/contributor/contributing.rst | 28 ++++ doc/source/contributor/getting-started.rst | 69 ++++++++ doc/source/history.rst | 1 - doc/source/index.rst | 3 +- doc/source/installation.rst | 14 +- lower-constraints.txt | 17 ++ rbd_iscsi_client/__init__.py | 9 +- releasenotes/source/conf.py | 54 ++++++ releasenotes/source/index.rst | 8 + releasenotes/source/unreleased.rst | 5 + requirements.txt | 3 +- setup.cfg | 24 ++- test-requirements.txt | 6 +- tools/lintstack.py | 4 +- tox.ini | 77 +++++---- 31 files changed, 567 insertions(+), 333 deletions(-) create mode 100644 .gitreview delete mode 100644 .travis.yml create mode 100644 .zuul.yaml create mode 100644 HACKING.rst delete mode 100644 HISTORY.rst delete mode 100644 Makefile create mode 100644 babel.cfg create mode 100644 doc/requirements.txt create mode 100644 doc/source/_extra/.placeholder create mode 100644 doc/source/_static/.placeholder delete mode 100644 doc/source/contributing.rst create mode 100644 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/getting-started.rst delete mode 100644 doc/source/history.rst create mode 100644 lower-constraints.txt create mode 100644 releasenotes/source/conf.py create mode 100644 releasenotes/source/index.rst create mode 100644 releasenotes/source/unreleased.rst diff --git a/.gitignore b/.gitignore index 84229f4..ec6c4c1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,10 @@ # Byte-compiled / optimized / DLL files +.* +!.coveragerc +!.gitignore +!.testr.conf +!.stestr.conf +!.zuul.yaml __pycache__/ *.py[cod] *$py.class @@ -44,8 +50,11 @@ htmlcov/ nosetests.xml coverage.xml *.cover +cover/ .hypothesis/ .pytest_cache/ +tools/lintstack.head.py +tools/pylint_exceptions # Translations *.mo @@ -100,3 +109,8 @@ ENV/ # mypy .mypy_cache/ + +# Files created by releasenotes build +releasenotes/build +RELEASENOTES.rst +releasenotes/notes/reno.cache diff --git a/.gitreview b/.gitreview new file mode 100644 index 0000000..0959532 --- /dev/null +++ b/.gitreview @@ -0,0 +1,4 @@ +[gerrit] +host=review.opendev.org +port=29418 +project=openstack/rbd-iscsi-client.git diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 6647893..0000000 --- a/.travis.yml +++ /dev/null @@ -1,17 +0,0 @@ -# Config file for automatic testing at travis-ci.org - -language: python - -cache: pip - -python: - - 3.8 - - 3.7 - - 3.6 - -# Command to install dependencies, e.g. pip install -r requirements.txt --use-mirrors -install: pip install -U tox-travis -r requirements.txt -r test-requirements.txt - -# Command to run tests, e.g. python setup.py test -script: tox - diff --git a/.zuul.yaml b/.zuul.yaml new file mode 100644 index 0000000..e454309 --- /dev/null +++ b/.zuul.yaml @@ -0,0 +1,26 @@ +- project: + templates: + - openstack-lower-constraints-jobs + - openstack-python3-xena-jobs + - publish-openstack-docs-pti + - check-requirements + - release-notes-jobs-python3 + check: + jobs: + - rbd-iscsi-client-code-coverage: + voting: false + +- job: + name: rbd-iscsi-client-code-coverage + parent: openstack-tox-cover + timeout: 2400 + irrelevant-files: + - ^(test-|)requirements.txt$ + - ^lower-constraints.txt$ + - ^.*\.rst$ + - ^rbd_iscsi_client/locale/.*$ + - ^doc/.*$ + - ^releasenotes/.*$ + - ^setup.cfg$ + - ^tools/.*$ + - ^tox.ini$ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 5b921d1..a28d03d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,127 +1,19 @@ -.. highlight:: shell +The source repository for this project can be found at: -============ -Contributing -============ + https://opendev.org/openstack/rbd-iscsi-client -Contributions are welcome, and they are greatly appreciated! Every little bit -helps, and credit will always be given. +Pull requests submitted through GitHub are not monitored. -You can contribute in many ways: +To start contributing to OpenStack, follow the steps in the contribution guide +to set up and use Gerrit: -Types of Contributions ----------------------- + https://docs.openstack.org/contributors/code-and-documentation/quick-start.html -Report Bugs -~~~~~~~~~~~ +Bugs should be filed on Launchpad: -Report bugs at https://github.com/hemna/rbd-iscsi-client/issues. + https://bugs.launchpad.net/rbd-iscsi-client -If you are reporting a bug, please include: +For more specific information about contributing to this repository, see the +cinder contributor guide: -* Your operating system name and version. -* Any details about your local setup that might be helpful in troubleshooting. -* Detailed steps to reproduce the bug. - -Fix Bugs -~~~~~~~~ - -Look through the GitHub issues for bugs. Anything tagged with "bug" and "help -wanted" is open to whoever wants to implement it. - -Implement Features -~~~~~~~~~~~~~~~~~~ - -Look through the GitHub issues for features. Anything tagged with "enhancement" -and "help wanted" is open to whoever wants to implement it. - -Write Documentation -~~~~~~~~~~~~~~~~~~~ - -RBD iSCSI Client could always use more documentation, whether as part of the -official RBD iSCSI Client docs, in docstrings, or even on the web in blog posts, -articles, and such. - -Submit Feedback -~~~~~~~~~~~~~~~ - -The best way to send feedback is to file an issue at https://github.com/hemna/rbd-iscsi-client/issues. - -If you are proposing a feature: - -* Explain in detail how it would work. -* Keep the scope as narrow as possible, to make it easier to implement. -* Remember that this is a volunteer-driven project, and that contributions - are welcome :) - -Get Started! ------------- - -Ready to contribute? Here's how to set up `rbd-iscsi-client` for local development. - -1. Fork the `rbd-iscsi-client` repo on GitHub. -2. Clone your fork locally:: - - $ git clone git@github.com:hemna/rbd-iscsi-client.git - -3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:: - - $ mkvirtualenv rbd-iscsi-client - $ cd rbd-iscsi-client/ - $ python setup.py develop - -4. Create a branch for local development:: - - $ git checkout -b name-of-your-bugfix-or-feature - - Now you can make your changes locally. - -5. When you're done making changes, check that your changes pass flake8 and the - tests, including testing other Python versions with tox:: - - $ tox -e pep8 - $ tox - - To get flake8 and tox, just pip install them into your virtualenv. - -6. Commit your changes and push your branch to GitHub:: - - $ git add . - $ git commit -m "Your detailed description of your changes." - $ git push origin name-of-your-bugfix-or-feature - -7. Submit a pull request through the GitHub website. - -Pull Request Guidelines ------------------------ - -Before you submit a pull request, check that it meets these guidelines: - -1. The pull request should include tests. -2. If the pull request adds functionality, the docs should be updated. Put - your new functionality into a function with a docstring, and add the - feature to the list in README.rst. -3. The pull request should work for Python 2.7, 3.4, 3.5 and 3.6, and for PyPy. Check - https://travis-ci.org/hemna/rbd-iscsi-client/pull_requests - and make sure that the tests pass for all supported Python versions. - -Tips ----- - -To run a subset of tests:: - - - $ tox -epy37 tests.test_rbd_iscsi_client - -Deploying ---------- - -A reminder for the maintainers on how to deploy. -Make sure all your changes are committed (including an entry in HISTORY.rst). -Then run:: - -$ bumpversion patch # possible: major / minor / patch -$ git push -$ git push --tags - -Travis will then deploy to PyPI if tests pass. + https://docs.openstack.org/cinderlib/latest/contributor/contributing.html diff --git a/HACKING.rst b/HACKING.rst new file mode 100644 index 0000000..009be3f --- /dev/null +++ b/HACKING.rst @@ -0,0 +1,58 @@ +rbd-iscsi-client Style Commandments +=================================== + +- Step 1: Read the OpenStack Style Commandments + https://docs.openstack.org/hacking/latest/ +- Step 2: Read on + +Cinder Specific Commandments +---------------------------- +- [N314] Check for vi editor configuration in source files. +- [N322] Ensure default arguments are not mutable. +- [N323] Add check for explicit import of _() to ensure proper translation. +- [N325] str() and unicode() cannot be used on an exception. Remove or use + six.text_type(). +- [N336] Must use a dict comprehension instead of a dict constructor with a + sequence of key-value pairs. +- [C301] timeutils.utcnow() from oslo_utils should be used instead of + datetime.now(). +- [C302] six.text_type should be used instead of unicode. +- [C303] Ensure that there are no 'print()' statements in code that is being + committed. +- [C304] Enforce no use of LOG.audit messages. LOG.info should be used instead. +- [C305] Prevent use of deprecated contextlib.nested. +- [C306] timeutils.strtime() must not be used (deprecated). +- [C307] LOG.warn is deprecated. Enforce use of LOG.warning. +- [C308] timeutils.isotime() must not be used (deprecated). +- [C309] Unit tests should not perform logging. +- [C310] Check for improper use of logging format arguments. +- [C311] Check for proper naming and usage in option registration. +- [C312] Validate that logs are not translated. +- [C313] Check that assertTrue(value) is used and not assertEqual(True, value). + +General +------- +- Use 'raise' instead of 'raise e' to preserve original traceback or exception + being reraised:: + + except Exception as e: + ... + raise e # BAD + + except Exception: + ... + raise # OKAY + + + +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 Cinder, please see +https://docs.openstack.org/cinder/latest/contributor/testing.html diff --git a/HISTORY.rst b/HISTORY.rst deleted file mode 100644 index e9adec4..0000000 --- a/HISTORY.rst +++ /dev/null @@ -1,8 +0,0 @@ -======= -History -======= - -0.1.0 (2019-06-12) ------------------- - -* First release on PyPI. diff --git a/LICENSE b/LICENSE index dc93458..68c771a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,16 +1,176 @@ -Apache Software License 2.0 -Copyright (c) 2019, Walter A. Boring IV + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ -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 a copy of the License at + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION -http://www.apache.org/licenses/LICENSE-2.0 + 1. Definitions. -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. diff --git a/Makefile b/Makefile deleted file mode 100644 index faa7cdd..0000000 --- a/Makefile +++ /dev/null @@ -1,88 +0,0 @@ -.PHONY: clean clean-test clean-pyc clean-build docs help -.DEFAULT_GOAL := help - -define BROWSER_PYSCRIPT -import os, webbrowser, sys - -try: - from urllib import pathname2url -except: - from urllib.request import pathname2url - -webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1]))) -endef -export BROWSER_PYSCRIPT - -define PRINT_HELP_PYSCRIPT -import re, sys - -for line in sys.stdin: - match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line) - if match: - target, help = match.groups() - print("%-20s %s" % (target, help)) -endef -export PRINT_HELP_PYSCRIPT - -BROWSER := python -c "$$BROWSER_PYSCRIPT" - -help: - @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST) - -clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts - -clean-build: ## remove build artifacts - rm -fr build/ - rm -fr dist/ - rm -fr .eggs/ - find . -name '*.egg-info' -exec rm -fr {} + - find . -name '*.egg' -exec rm -f {} + - -clean-pyc: ## remove Python file artifacts - find . -name '*.pyc' -exec rm -f {} + - find . -name '*.pyo' -exec rm -f {} + - find . -name '*~' -exec rm -f {} + - find . -name '__pycache__' -exec rm -fr {} + - -clean-test: ## remove test and coverage artifacts - rm -fr .tox/ - rm -f .coverage - rm -fr htmlcov/ - rm -fr .pytest_cache - -lint: ## check style with flake8 - tox -e pep8 - -test: ## run tests quickly with the default Python - python setup.py test - -test-all: ## run tests on every Python version with tox - tox - -coverage: ## check code coverage quickly with the default Python - coverage run --source rbd_iscsi_client setup.py test - coverage report -m - coverage html - $(BROWSER) htmlcov/index.html - -docs: ## generate Sphinx HTML documentation, including API docs - rm -f docs/rbd_iscsi_client.rst - rm -f docs/modules.rst - sphinx-apidoc -o docs/ rbd_iscsi_client - $(MAKE) -C docs clean - $(MAKE) -C docs html - $(BROWSER) docs/_build/html/index.html - -servedocs: docs ## compile the docs watching for changes - watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D . - -release: dist ## package and upload a release - twine upload dist/* - -dist: clean ## builds source and wheel package - python setup.py sdist - python setup.py bdist_wheel - ls -l dist - -install: clean ## install the package to the active Python's site-packages - python setup.py install diff --git a/README.rst b/README.rst index 1ded51e..535d40a 100644 --- a/README.rst +++ b/README.rst @@ -6,25 +6,11 @@ RBD iSCSI Client .. image:: https://img.shields.io/pypi/v/rbd-iscsi-client.svg :target: https://pypi.python.org/pypi/rbd-iscsi-client -.. image:: https://img.shields.io/travis/hemna/rbd-iscsi-client.svg - :target: https://travis-ci.com/hemna/rbd-iscsi-client +.. image:: https://img.shields.io/pypi/pyversions/rbd-iscsi-client.svg + :target: https://pypi.python.org/pypi/rbd-iscsi-client -.. image:: https://readthedocs.org/projects/rbd-iscsi-client/badge/?version=latest - :target: https://rbd-iscsi-client.readthedocs.io/en/latest/?badge=latest - :alt: Documentation Status - -.. image:: https://pyup.io/repos/github/hemna/rbd-iscsi-client/shield.svg - :target: https://pyup.io/repos/github/hemna/rbd-iscsi-client/ - :alt: Updates - - - -This is a REST client that talks to ceph-iscsi's rbd-target-api to export -rbd images/volumes to an iSCSI initiator. - - -* Free software: Apache Software License 2.0 -* Documentation: https://rbd-iscsi-client.readthedocs.io. +.. image:: https://img.shields.io/:license-apache-blue.svg + :target: http://www.apache.org/licenses/LICENSE-2.0 Overview @@ -74,7 +60,8 @@ This package makes use of the rbd-target-api from ceph-iscsi_ package. .. _ceph-iscsi: https://github.com/ceph/ceph-iscsi -This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. +This package was originally created with Cookiecutter_ and the +`audreyr/cookiecutter-pypackage`_ project template. .. _Cookiecutter: https://github.com/audreyr/cookiecutter .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage diff --git a/babel.cfg b/babel.cfg new file mode 100644 index 0000000..efceab8 --- /dev/null +++ b/babel.cfg @@ -0,0 +1 @@ +[python: **.py] diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..3efcf48 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,7 @@ +# The order of packages is significant, because pip processes them in the order +# of appearance. Changing the order has an impact on the overall integration +# process, which may cause wedges in the gate later. +openstackdocstheme>=2.2.7 # Apache-2.0 +reno>=3.1.0 # Apache-2.0 +doc8>=0.6.0 # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 # BSD diff --git a/doc/source/_extra/.placeholder b/doc/source/_extra/.placeholder new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/conf.py b/doc/source/conf.py index 32a5270..59f36ac 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -41,7 +41,7 @@ master_doc = 'index' # General information about the project. project = u'rbd-iscsi-client' copyright = u"2019, Walter A. Boring IV" -author = u"Walter A. Boring IV" +author = u"Cinder Contributors" # The version info for the project you're documenting, acts as replacement # for |version| and |release|, also used in various other places throughout @@ -60,7 +60,7 @@ release = version_info.release_string() language = None add_function_parentheses = True -add_module_names = True +add_module_names = False # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -68,7 +68,7 @@ add_module_names = True exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'native' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -116,7 +116,7 @@ latex_elements = { latex_documents = [ (master_doc, 'rbd_iscsi_client.tex', u'RBD iSCSI Client Documentation', - u'Walter A. Boring IV', 'manual'), + author, 'manual'), ] @@ -141,12 +141,13 @@ texinfo_documents = [ u'RBD iSCSI Client Documentation', author, 'rbd_iscsi_client', - 'One line description of project.', + "Provides a REST client that talks to ceph-isci's rbd-target-api " + "to export rbd images/volumes to an iSCSI initiator.", 'Miscellaneous'), ] # -- Options for openstackdocstheme ----------------------------------- -repository_name = 'hemna/rbd-iscsi-client' -bug_project = 'rbd-iscsi-client' -bug_tag = '' +openstackdocs_repo_name = 'openstack/rbd-iscsi-client' +openstackdocs_bug_project = 'rbd-iscsi-client' +openstackdocs_bug_tag = 'doc' diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index ac7b6bc..0000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000..d2feec3 --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,28 @@ +============================ +So You Want to Contribute... +============================ + +For general information on contributing to OpenStack, please check out the +`contributor guide `_ to get started. +It covers all the basics that are common to all OpenStack projects: the +accounts you need, the basics of interacting with our Gerrit review system, how +we communicate as a community, etc. + +The rbd-iscsi-client library is maintained by the OpenStack Cinder project. To +understand our development process and how you can contribute to it, please +look at the Cinder project's general contributor's page: +http://docs.openstack.org/cinder/latest/contributor/contributing.html + +Getting Started +--------------- + +Here are some :doc:`tips for setting up rbd-iscsi-client for local development +`. + +Integration Testing +------------------- + +The rbd-iscsi-client library is consumed by the Cinder RBD ISCSI driver +(``cinder.volume.drivers.ceph.rbd_iscsi.RBDISCSIDriver``). The driver, +and hence this library, is tested by the ``cinder-plugin-ceph-iscsi-tempest`` +job defined in the ``.zuul.yaml`` file in the Cinder code repository. diff --git a/doc/source/contributor/getting-started.rst b/doc/source/contributor/getting-started.rst new file mode 100644 index 0000000..1f5eb8b --- /dev/null +++ b/doc/source/contributor/getting-started.rst @@ -0,0 +1,69 @@ +:orphan: + +.. highlight:: shell + +.. _getting-started: + +Get Started! +============ + +Ready to contribute? + +Local setup +----------- + +Here's how to set up ``rbd-iscsi-client`` for local development. + +1. Clone the ``rbd-iscsi-client`` git repository:: + + $ git clone https://opendev.org/openstack/rbd-iscsi-client.git + +2. Install your local copy into a virtualenv. Assuming you have + virtualenvwrapper installed, this is how you set up your repo for local + development:: + + $ mkvirtualenv rbd-iscsi-client + $ cd rbd-iscsi-client/ + $ python setup.py develop + +3. Create a branch for local development:: + + $ git checkout -b name-of-your-bugfix-or-feature + + Now you can make your changes locally. + +4. When you're done making changes, check that your changes pass flake8 and the + tests, including testing other Python versions with tox:: + + $ tox -e pep8 + $ tox + + To get flake8 and tox, just pip install them into your virtualenv. + +5. Commit your changes and push them to the opendev gerrit. (Please follow + the OpenStack standard for commit messages. If you haven't already, you'll + need to install the ``git-review`` package from your operating system + distro first):: + + $ git add . + $ git commit + $ git review + +Submission Guidelines +--------------------- + +Before you submit a patch, check that it meets these guidelines: + +1. The patch should include tests. +2. If the patch adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring and add a + release note to your patch. +3. The patch should work for at least Python 3.6 and 3.8. + +Tips +---- + +To run a subset of tests:: + + + $ tox -epy38 tests.test_rbd_iscsi_client diff --git a/doc/source/history.rst b/doc/source/history.rst deleted file mode 100644 index 5f2e348..0000000 --- a/doc/source/history.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../HISTORY.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 77274b8..8b32f88 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,8 +8,7 @@ Welcome to RBD iSCSI Client's documentation! readme installation usage - contributing - history + contributor/contributing Indices and tables ================== diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 0cc4641..aa84429 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -14,7 +14,8 @@ To install RBD iSCSI Client, run this command in your terminal: $ pip install rbd-iscsi-client -This is the preferred method to install RBD iSCSI Client, as it will always install the most recent stable release. +This is the preferred method to install RBD iSCSI Client, as it will always +install the most recent stable release. If you don't have `pip`_ installed, this `Python installation guide`_ can guide you through the process. @@ -26,19 +27,20 @@ you through the process. From sources ------------ -The sources for RBD iSCSI Client can be downloaded from the `Github repo`_. +The sources for RBD iSCSI Client can be downloaded from the `git repo`_ +hosted on opendev.org. You can either clone the public repository: .. code-block:: console - $ git clone git://github.com/hemna/rbd-iscsi-client + $ git clone https://opendev.org/openstack/rbd-iscsi-client.git Or download the `tarball`_: .. code-block:: console - $ curl -OL https://github.com/hemna/rbd-iscsi-client/tarball/master + $ curl -OL https://opendev.org/openstack/rbd-iscsi-client/archive/master.tar.gz Once you have a copy of the source, you can install it with: @@ -47,5 +49,5 @@ Once you have a copy of the source, you can install it with: $ python setup.py install -.. _Github repo: https://github.com/hemna/rbd-iscsi-client -.. _tarball: https://github.com/hemna/rbd-iscsi-client/tarball/master +.. _git repo: https://opendev.org/openstack/rbd-iscsi-client +.. _tarball: https://opendev.org/openstack/rbd-iscsi-client/archive/master.tar.gz diff --git a/lower-constraints.txt b/lower-constraints.txt new file mode 100644 index 0000000..d112221 --- /dev/null +++ b/lower-constraints.txt @@ -0,0 +1,17 @@ +Babel==2.3.4 +coverage==4.1 +doc8==0.6.0 +ddt==1.2.1 +hacking==3.1.0 +openstackdocstheme==2.2.7 +oslo.i18n==3.24.0 +oslo.log==3.44.0 +oslo.utils==3.36.0 +oslotest==3.2.0 +pbr==5.4.1 +reno==3.1.0 +requests==2.14.2 +sphinx==2.0.0 +stestr==1.0.0 +testscenarios==0.4 +testtools==2.2.0 diff --git a/rbd_iscsi_client/__init__.py b/rbd_iscsi_client/__init__.py index a5a5f1d..ab551f2 100644 --- a/rbd_iscsi_client/__init__.py +++ b/rbd_iscsi_client/__init__.py @@ -12,14 +12,9 @@ import pbr.version -__all_ = ['__version__'] - -__author__ = """Walter A. Boring IV""" -__email__ = 'waboring@hemna.com' - version_info = pbr.version.VersionInfo('rbd-iscsi-client') try: - version = version_info.version_string() + __version__ = version_info.version_string() except AttributeError: - version = None + __version__ = None diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py new file mode 100644 index 0000000..6fb5bb5 --- /dev/null +++ b/releasenotes/source/conf.py @@ -0,0 +1,54 @@ +# 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 a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# Refer to the Sphinx documentation for advice on configuring this file: +# +# http://www.sphinx-doc.org/en/stable/config.html + +# -- General configuration ------------------------------------------------ + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'reno.sphinxext', + 'openstackdocstheme', +] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'native' + +# General information about the project. +copyright = u'2021, Cinder Contributors' + +# Release notes are unversioned, so we don't need to set version and release +version = '' +release = '' + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'openstackdocs' + +# -- Options for openstackdocstheme ------------------------------------------- + +openstackdocs_repo_name = 'openstack/rbd-iscsi-client' +openstackdocs_bug_project = 'rbd-iscsi-client' +openstackdocs_bug_tag = '' diff --git a/releasenotes/source/index.rst b/releasenotes/source/index.rst new file mode 100644 index 0000000..97ecb33 --- /dev/null +++ b/releasenotes/source/index.rst @@ -0,0 +1,8 @@ +================================ + rbd-iscsi-client Release Notes +================================ + +.. toctree:: + :maxdepth: 1 + + unreleased diff --git a/releasenotes/source/unreleased.rst b/releasenotes/source/unreleased.rst new file mode 100644 index 0000000..875030f --- /dev/null +++ b/releasenotes/source/unreleased.rst @@ -0,0 +1,5 @@ +============================ +Current Series Release Notes +============================ + +.. release-notes:: diff --git a/requirements.txt b/requirements.txt index cb39030..90b1957 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,6 +6,5 @@ pbr!=2.1.0,>=5.4.1 # Apache-2.0 Babel!=2.4.0,>=2.3.4 # BSD oslo.log>=3.44.0 # Apache-2.0 oslo.i18n>=3.24.0 # Apache-2.0 -oslo.utils>=3.34.0 # Apache-2.0 +oslo.utils>=3.36.0 # Apache-2.0 requests>=2.14.2,!=2.20.0 # Apache-2.0 -six>=1.10.0 # MIT diff --git a/setup.cfg b/setup.cfg index 03d86ad..1d96092 100644 --- a/setup.cfg +++ b/setup.cfg @@ -6,16 +6,18 @@ name = rbd-iscsi-client summary = "REST client to talk to rbd-target-api" description_file = README.rst -author = Walter A. Boring IV -author-email = waboring@hemna.com -home-page = http://github.com/hemna/rbd-iscsi-client +author = OpenStack +author_email = openstack-discuss@lists.openstack.org +home_page = http://opendev.org/openstack/rbd-iscsi-client license_file = LICENSE -classifier = +python_requires = >=3.6 +classifiers = Environment :: OpenStack Intended Audience :: Information Technology Intended Audience :: System Administrators License :: OSI Approved :: Apache Software License Natural Language :: English + Programming Language :: Python :: 3 :: Only Programming Language :: Python :: 3 Programming Language :: Python :: 3.6 Programming Language :: Python :: 3.7 @@ -46,3 +48,17 @@ skip_authors = 1 [upload_sphinx] upload-dir = doc/build/html + +[compile_catalog] +directory = rbd_iscsi_client/locale +domain = rbd-iscsi-client + +[update_catalog] +domain = rbd-iscsi-client +output_dir = rbd_iscsi_client/locale +input_file = rbd_iscsi_client/locale/rbd-iscsi-client.pot + +[extract_messages] +keywords = _ gettext ngettext l_ lazy_gettext +mapping_file = babel.cfg +output_file = rbd_iscsi_client/locale/rbd-iscsi-client.pot diff --git a/test-requirements.txt b/test-requirements.txt index d1b0ef6..591493e 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -1,17 +1,13 @@ - # The order of packages is significant, because pip processes them in the order # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. -hacking!=3.1.0,>=2.2.0 # Apache-2.0 +hacking>=3.1.0,<3.2.0 # Apache-2.0 flake8-import-order # LGPLv3 flake8-logging-format>=0.6.0 #Apache-2.0 coverage!=4.4,>=4.1 # Apache-2.0 ddt>=1.2.1 # MIT -reno>=3.1.0 # Apache-2.0 -sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD -openstackdocstheme>=1.18.1 # Apache-2.0 oslotest>=3.2.0 # Apache-2.0 testscenarios>=0.4 # Apache-2.0/BSD testtools>=2.2.0 # MIT diff --git a/tools/lintstack.py b/tools/lintstack.py index 20700ab..b35cfe5 100755 --- a/tools/lintstack.py +++ b/tools/lintstack.py @@ -44,7 +44,7 @@ ignore_messages = [ "Module 'hashlib' has no 'sha224' member", ] -ignore_modules = ["os_brick/tests/", +ignore_modules = ["rbd_iscsi_client/tests/", "tools/lintstack.head.py"] KNOWN_PYLINT_EXCEPTIONS_FILE = "tools/pylint_exceptions" @@ -145,7 +145,7 @@ class ErrorKeys(object): def run_pylint(): buff = StringIO() reporter = text.ParseableTextReporter(output=buff) - args = ["--include-ids=y", "-E", "os_brick"] + args = ["--include-ids=y", "--errors-only", "rbd_iscsi_client"] lint.Run(args, reporter=reporter, exit=False) val = buff.getvalue() buff.close() diff --git a/tox.ini b/tox.ini index 7145ec0..ada5aba 100644 --- a/tox.ini +++ b/tox.ini @@ -1,69 +1,71 @@ [tox] -minversion = 2.0 -envlist = py36,py37,py38,pep8 -skipdist = True - -[travis] -python = - 3.8: py38 - 3.7: py37 - 3.6: py36 +minversion = 3.18.0 +requires = virtualenv>=20.4.2 +# python runtimes: https://governance.openstack.org/tc/reference/project-testing-interface.html#tested-runtimes +envlist = py3,pep8 +skipsdist = True +# this allows tox to infer the base python from the environment name +# and override any basepython configured in this file +ignore_basepython_conflict=true [testenv] +basepython = python3 usedevelop = True setenv = - VIRTUAL_EN={envdir} + VIRTUAL_ENV={envdir} + PYTHONWARNINGS=default::DeprecationWarning OS_TEST_PATH=./rbd_iscsi_client/tests OS_TEST_TIMEOUT=60 OS_STDOUT_CAPTURE=1 OS_STDERR_CAPTURE=1 - PYTHONPATH = {toxinidir} - -install_command = pip install {opts} {packages} deps = - -c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt} - -r{toxinidir}/requirements.txt - -r{toxinidir}/test-requirements.txt + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/test-requirements.txt + -r{toxinidir}/requirements.txt commands = + find . -ignore_readdir_race -type f -name "*.pyc" -delete stestr run {posargs} stestr slowest -whitelist_externals = bash +allowlist_externals = bash find passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY [testenv:pep8] -basepython = python3 -envdir = {toxworkdir}/pep8 commands = flake8 {posargs} [testenv:debug] -basepython = python3 commands = find . type f -name "*.pyc" -delete oslo_debug_helper {posargs} [testenv:fast8] -basepython = python3 +# Use same environment directory as pep8 env to save space and install time envdir = {toxworkdir}/pep8 commands = {toxinidir}/tools/fast8.sh [testenv:pylint] -basepython = python3 +# FIXME: +# 1. pylint uses logilab.astng.rebuilder, and under py3.8 it gives this +# error: ImportError: cannot import name 'Str' from '_ast' +# 2. pylint is pinned really low because tools/lintstack.py uses an option +# '--include-ids=y' that was removed from pylint at some point +# 3. even so, this still doesn't work ... problem generating the +# tools/pylint_exceptions file that's used to translate from codes +# to messages +basepython = python3.6 deps = - -c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt} - -r{toxinidir}/requirements.txt - pylint==0.26.0 + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/requirements.txt + pylint==0.26.0 commands = bash tools/lintstack.sh [testenv:venv] -basepython = python3 commands = {posargs} [testenv:cover] -basepython = python3 # To see the report of missing coverage add to commands # coverage report --show-missing setenv = @@ -76,14 +78,25 @@ commands = coverage xml -o cover/coverage/xml [testenv:docs] -basepython = python3 -commands = python setup.py build_sphinx +deps = + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/doc/requirements.txt +commands = + doc8 + rm -rf doc/build .autogenerated doc/source/api + sphinx-build -W -b html doc/source doc/build/html +allowlist_externals = rm + +[doc8] +ignore-path=.tox,*.egg-info,doc/build,.eggs/*/EGG-INFO/*.txt +extension=.txt,.rst [testenv:releasenotes] -basepython = python3 +deps = + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/doc/requirements.txt commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html - [flake8] # Following checks are ignored on purpose. # @@ -108,7 +121,6 @@ max-complexity=30 import_exceptions = rbd_iscsi_client.i18n [testenv:bindep] -basepython = python3 # Do not install any requirements. We want this to be fast and work even if # system dependencies are missing, since it's used to tell you what system # dependencies are missing! This also means that bindep must be installed @@ -120,7 +132,6 @@ commands = bindep test usedevelop = False [testenv:lower-constraints] -basepython = python3 deps = -c{toxinidir}/lower-constraints.txt -r{toxinidir}/test-requirements.txt