From 403831dd3a663610a3cde35c90e1ff2872a95080 Mon Sep 17 00:00:00 2001 From: Dan Callaghan Date: Oct 25 2017 08:15:40 +0000 Subject: [PATCH 1/3] docs: use sphinxcontrib.issuetracker extension ... rather than manually filling in all the issue URLs. Also slightly reformatted the existing changelog entries to follow a more conventional style, with the issue number in parentheses at the end of the item. --- diff --git a/docs/conf.py b/docs/conf.py index c5bed24..6772736 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,6 +42,7 @@ extensions = [ 'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinxcontrib.autohttp.flask', + 'sphinxcontrib.issuetracker', ] # Add any paths that contain templates here, relative to this directory. @@ -188,3 +189,42 @@ epub_exclude_files = ['search.html'] # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'https://docs.python.org/2/': 'python-intersphinx.inv'} + +# Configuration for issue tracker magic linking. +issuetracker = None +issuetracker_url = 'https://pagure.io/' +issuetracker_project = 'waiverdb' + +# Until Pagure support is merged: https://github.com/ignatenkobrain/sphinxcontrib-issuetracker/pull/15 +import requests +from sphinxcontrib.issuetracker import Issue +PAGURE_URL = '{0.url}/{0.project}/issue/{1}' +PAGURE_API_URL = '{0.url}/api/0/{0.project}/issue/{1}' +HEADERS = { + 'User-Agent': 'sphinxcontrib-issuetracker' +} +def get(app, url): + try: + response = requests.get(url, headers=HEADERS) + if response.status_code == requests.codes.ok: + return response + elif response.status_code != requests.codes.not_found: + msg = 'GET {0.url} failed with code {0.status_code}' + app.warn(msg.format(response)) + except IOError as e: + msg = 'GET {0} failed with error: {1}' + app.warn(msg.format(url, e)) +def lookup_pagure_issue(app, tracker_config, issue_id): + if not tracker_config.url: + raise ValueError('URL required, try: https://pagure.io/') + issue_url = PAGURE_URL.format(tracker_config, issue_id) + response = get(app, PAGURE_API_URL.format(tracker_config, issue_id)) + if response: + title = response.json()['title'] + closed = response.json()['status'] != 'Open' + return Issue(id=issue_id, title=title, closed=closed, url=issue_url) + else: + return Issue(id=issue_id, title=None, closed=False, url=issue_url) + +def setup(app): + app.connect('issuetracker-lookup-issue', lookup_pagure_issue) diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 82c29d8..36ed945 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -9,16 +9,12 @@ Released 26 Sep 2017. A number of issues have been resolved in this release: -* `Issue 73`_: Fixed some type errors in the API docs examples. +* Fixed some type errors in the API docs examples (#73). -* `Issue 74`_: Updated README to recommend installing package dependencies using dnf builddep. +* Updated README to recommend installing package dependencies using dnf builddep (#74). -* `Issue 75`_: Fixed the health check API to return a proper error if the application is not - able to serve requests. - -.. _Issue 73: https://pagure.io/waiverdb/issue/73 -.. _Issue 74: https://pagure.io/waiverdb/issue/74 -.. _Issue 75: https://pagure.io/waiverdb/issue/75 +* Fixed the health check API to return a proper error if the application is not + able to serve requests (#75). Other updates ------------- diff --git a/waiverdb.spec b/waiverdb.spec index 740d57b..f17994b 100644 --- a/waiverdb.spec +++ b/waiverdb.spec @@ -14,6 +14,7 @@ BuildRequires: python2-devel BuildRequires: python2-setuptools BuildRequires: python2-sphinx BuildRequires: python-sphinxcontrib-httpdomain +BuildRequires: python-sphinxcontrib-issuetracker BuildRequires: python2-flask %if 0%{?fedora} > 25 BuildRequires: python2-sqlalchemy From 5a76bd0970993ef50ef5051295693ac1c4f2f813 Mon Sep 17 00:00:00 2001 From: Dan Callaghan Date: Oct 25 2017 08:15:43 +0000 Subject: [PATCH 2/3] don't fail the RPM build on Sphinx warnings Now that we are using sphinxcontrib-issuetracker, some warnings are unfortunately expected when we build inside Koji, because it won't be able to reach the network: WARNING: GET https://pagure.io/api/0/waiverdb/issue/73 failed with error: ... We can just ignore them. The Jenkins pipeline will still build the docs with SPHINXOPTS=-W so we will still notice any *other* warnings that crop up. --- diff --git a/waiverdb.spec b/waiverdb.spec index f17994b..fb743b9 100644 --- a/waiverdb.spec +++ b/waiverdb.spec @@ -83,7 +83,7 @@ against test results. %build %py2_build %if 0%{?fedora} -make -C docs html text +make -C docs SPHINXOPTS= html text %endif %install From 2d974e7bc98cab3f3deb78a9b2ee1d9f88ec2699 Mon Sep 17 00:00:00 2001 From: Dan Callaghan Date: Oct 25 2017 08:15:43 +0000 Subject: [PATCH 3/3] docs: add a roadmap document --- diff --git a/docs/index.rst b/docs/index.rst index a6f47bd..4a92168 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ test results. developer-guide api release-notes + todo diff --git a/docs/todo.rst b/docs/todo.rst new file mode 100644 index 0000000..fe51fa5 --- /dev/null +++ b/docs/todo.rst @@ -0,0 +1,42 @@ +Roadmap +======= + +This describes some plans for the future of WaiverDB. Items are listed in +approximate order of importance. + +Using WaiverDB +-------------- + +Currently there is no easy way to actually *use* WaiverDB as a user submitting +waivers. Ultimately we envisage that the consuming tools (for example, Bodhi) +will include some user interface elements to create new waivers in the same +place where they show the failing test results. However as a stop-gap there is: + +* #82: Provide a command-line interface to submit waivers + +There is one additional wrinkle. WaiverDB deployments running in OpenShift +cannot use Kerberos authentication, because clients mostly default to +``dns_canonicalize_hostname=true`` which is fundamentally incompatible with how +OpenShift routes traffic to applications. In that case, something like SSL +certification authentication will need to be used instead: + +* #76: Support SSL certificate authentication + +But we can't reasonably expect end users to obtain an SSL certificate for +submitting waivers, so we will need the consuming tool (Bodhi or equivalent) to +make the request to WaiverDB on behalf of the real human user. In that case +WaiverDB will need to trust the calling service to tell it who the real human +user was: + +* #77: Allow "proxy user" waiving for a configured list of "super users" + +Results may be absent +--------------------- + +One situation we anticipate is that a gating point is being held up a slow test +system or an outage in the infrastructure. In some cases (for example, shipping +urgent security advisories) humans may decide that it is worth the risk to +bypass the test requirement *even if there is no result yet*. + +* #80: Ability to waive the absence of a result +* #81: Ability to waive all results