From 8a387e4889b6d32d589240449113b430aa5a0676 Mon Sep 17 00:00:00 2001 From: Dan Callaghan Date: Oct 27 2017 00:41:06 +0000 Subject: [PATCH 1/5] 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 e084209..47ac249 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,6 +37,7 @@ extensions = [ 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinxcontrib.autohttp.flask', + 'sphinxcontrib.issuetracker', ] # Add any paths that contain templates here, relative to this directory. @@ -182,3 +183,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 = 'greenwave' + +# 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 2ee336d..c742770 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -22,21 +22,21 @@ Released 27 Sep 2017. A number of issues have been resolved in this release: -* `Issue 34`_: Expanded :http:post:`/api/v1.0/decision` to accept a list of dicts - as the subject of a decision. -* `Issue 35`_: For safety, the policies are loaded with yaml.safe_load_all. -* `Issue 36`_: Corrected the API docs examples. -* `Issue 60`_: Added type checks when loading the policies. -* `Issue 65`_: Added JSONP support. -* `Issue 72`_: Added a new HTTP API endpoint :http:get:`/api/v1.0/policies` exposing - raw policies. -* `Issue 77`_: Employed an actively-invalidated cache mechanism to cache resultsdb - and waiverdb results in order to improve gating performance. -* `Issue 78`_: Removed the init methods on our YAMLObject classes which are not - called at all. -* `Issue 83`_: Greenwave now sends POST requests for getting waivers to avoid - HTTP Error 413. -* `Issue 87`_: Greenwave now publishes messages when decision contexts change. +* Expanded :http:post:`/api/v1.0/decision` to accept a list of dicts + as the subject of a decision (#34). +* For safety, the policies are loaded with yaml.safe_load_all (#35). +* Corrected the API docs examples (#36). +* Added type checks when loading the policies (#60). +* Added JSONP support (#65). +* Added a new HTTP API endpoint :http:get:`/api/v1.0/policies` exposing + raw policies (#72). +* Employed an actively-invalidated cache mechanism to cache resultsdb + and waiverdb results in order to improve gating performance (#77). +* Removed the init methods on our YAMLObject classes which are not + called at all (#78). +* Greenwave now sends POST requests for getting waivers to avoid + HTTP Error 413 (#83). +* Greenwave now publishes messages when decision contexts change (#87). Other updates ------------- @@ -48,17 +48,6 @@ Other updates Also numerous improvements have made to the test and docs for Greenwave. -.. _Issue 34: https://pagure.io/greenwave/issue/34 -.. _Issue 35: https://pagure.io/greenwave/issue/35 -.. _Issue 36: https://pagure.io/greenwave/issue/36 -.. _Issue 60: https://pagure.io/greenwave/issue/60 -.. _Issue 65: https://pagure.io/greenwave/issue/65 -.. _Issue 72: https://pagure.io/greenwave/issue/72 -.. _Issue 77: https://pagure.io/greenwave/issue/77 -.. _Issue 78: https://pagure.io/greenwave/issue/78 -.. _Issue 83: https://pagure.io/greenwave/issue/83 -.. _Issue 87: https://pagure.io/greenwave/issue/87 - Greenwave 0.1 ============= diff --git a/greenwave.spec b/greenwave.spec index 2353373..01fdc5d 100644 --- a/greenwave.spec +++ b/greenwave.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 BuildRequires: python2-pytest BuildRequires: python2-requests diff --git a/tox.ini b/tox.ini index 2c4b095..2833cf2 100644 --- a/tox.ini +++ b/tox.ini @@ -33,6 +33,6 @@ commands = [flake8] show-source = True max-line-length = 100 -exclude = .git,.tox,dist,*egg,*fedmsg.d +exclude = .git,.tox,dist,*egg,*fedmsg.d,docs # E265 block comment should start with '# ' ignore = E265 From cba4066a63d624d3d84ec09c9808d27fffdb297e Mon Sep 17 00:00:00 2001 From: Dan Callaghan Date: Oct 27 2017 00:41:09 +0000 Subject: [PATCH 2/5] docs: no code highlighting for HTTP responses The Pygments lexer for 'http' only supports HTTP *requests*, not responses. It's expecting the block to start with an HTTP method like GET, etc. If we try to highlight HTTP responses, it causes a Sphinx warning like this: docs/api.rst:1: WARNING: Could not lex literal_block as "http". Highlighting skipped. --- diff --git a/greenwave/api_v1.py b/greenwave/api_v1.py index 932b32c..155d819 100644 --- a/greenwave/api_v1.py +++ b/greenwave/api_v1.py @@ -20,7 +20,7 @@ def version(): **Sample response**: - .. sourcecode:: http + .. sourcecode:: none HTTP/1.0 200 Content-Length: 228 @@ -47,7 +47,7 @@ def get_policies(): **Sample response**: - .. sourcecode:: http + .. sourcecode:: none HTTP/1.0 200 Content-Length: 228 @@ -128,7 +128,7 @@ def make_decision(): **Sample response**: - .. sourcecode:: http + .. sourcecode:: none HTTP/1.0 200 Content-Length: 228 From 03572c289187f27f09ca7e075ea8724a5b9074aa Mon Sep 17 00:00:00 2001 From: Dan Callaghan Date: Oct 27 2017 00:41:09 +0000 Subject: [PATCH 3/5] docs: don't configure _static directory Fixes this Sphinx warning: WARNING: html_static_path entry u'_static' does not exist --- diff --git a/docs/conf.py b/docs/conf.py index 47ac249..237316c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,7 +100,8 @@ html_theme = 'alabaster' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = ['_static'] +html_static_path = [] # -- Options for HTMLHelp output ------------------------------------------ From a212eb02cf8426442f7079dda70652800b486254 Mon Sep 17 00:00:00 2001 From: Dan Callaghan Date: Oct 27 2017 00:41:09 +0000 Subject: [PATCH 4/5] fail the docs build on Sphinx warnings We want Jenkins to tell us about this, if we accidentally introduce problems in our docs that trigger a Sphinx warning. But we *don't* want the RPM build to fail if there's warnings, because we expect some from sphinxcontrib-issuetracker if it fails to talk on the network when we build in Koji. --- diff --git a/docs/Makefile b/docs/Makefile index e9941b5..db4017e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -W SPHINXBUILD = sphinx-build SPHINXPROJ = Greenwave SOURCEDIR = . @@ -17,4 +17,4 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/greenwave.spec b/greenwave.spec index 01fdc5d..8c37bad 100644 --- a/greenwave.spec +++ b/greenwave.spec @@ -51,7 +51,7 @@ WaiverDB. %build %py2_build %if 0%{?fedora} -make -C docs html text +make -C docs SPHINXOPTS= html text %endif %install From 0d8dd45528d267f2e537cdead1352643601e569c Mon Sep 17 00:00:00 2001 From: Dan Callaghan Date: Oct 27 2017 01:23:49 +0000 Subject: [PATCH 5/5] docs: add a roadmap document --- diff --git a/docs/index.rst b/docs/index.rst index e06906e..7ced87e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,7 @@ gating points in a software delivery pipeline, based on test results stored in api contributing release-notes + todo Indices and tables diff --git a/docs/todo.rst b/docs/todo.rst new file mode 100644 index 0000000..aaf36d8 --- /dev/null +++ b/docs/todo.rst @@ -0,0 +1,76 @@ +Roadmap +======= + +This document describes some plans for the future of Greenwave. Items are +listed in approximate order of importance. + +Support for STOMP messaging +--------------------------- + +Like WaiverDB, we want to use Greenwave in environments which have +a STOMP-compatible message bus (#107). + +Per-package policies +-------------------- + +The `Greenwave focus document +`_ +anticipated the need for per-package policies, as a way for package owners to +opt *in* to *extra* checks. Therefore it was considered a low priority in the +first implementation of Greenwave. + +However, it turned out to be more important as a way to opt *out* of certain +checks. For example, certain packages are too large to be tested by abidiff +(see `pull request 95 `_). And the +new Fedora CI Pipeline is only testing a small (but growing) subset of packages +in the distribution (#61, #75). + +Greenwave currently contains short-term solutions for both of those problems, +but a more general way of expressing policies for specific packages is desired. + +Finding the right value for "subject" +------------------------------------- + +Greenwave is intentionally unaware of the meaning of the different keys and +values making up the "subject" of each decision. + +In the HTTP API, it is up to the caller to supply a suitable set of key-values +describing the "subject" and Greenwave uses these as is to look up results in +ResultsDB. + +However this does not naturally translate into a message-driven asynchronous +interface. When Greenwave receives a message about a new result or a new +waiver, there is no clear way to determine which *subset* of the key-values +make up the "subject" that consuming tools are interested in (#92). + +And the design also led to some ambiguities when Bodhi needs a decision about +an update which also consists of a set of builds (#68, #74). + +It may be necessary to come up with a different design for how Greenwave and +its consuming tools identify the "subject" of a decision. + +User-defined policies +--------------------- + +Greenwave currently represents policies as YAML configuration, which made the +initial implementation very easy. However there is a downside: changing the +policy effectively means changing Greenwave's configuration. In the case of +Fedora's Greenwave deployment, this means patching Ansible roles (potentially +with a freeze break exception), running a playbook to apply the configuration, +and then having OpenShift re-deploy all pods. + +As Greenwave becomes integral to the release process, we expect that users will +be interested in defining their own policies. Here, "user" may mean people like +distro QA representatives, product managers, or individual package owners. +Every small tweak to the policy should not require the involvement of +sysadmins. + +This is related to the "per-package policies" item above. One possible way to +support per-package policies is to make Greenwave consult a YAML policy file in +the dist-git tree for each package when it makes a decision. Distro-wide +policies would remain in Greenwave's configuration. This design may be enough +to satisfy this need for user-defined policies. + +Another option is to replace the current YAML format for policies with +a database representation, and provide an HTTP API, CLI, and web UI for viewing +and updating policies.