docs: update frontpage

- Describe the system's core mechanism
- Describe the workflow more precisely
- Add pointers for main audiences
- Generate link to published GitHub issues from settings

Author: fricklerhandwerk

src/shared/templates/base.html

@@ -87,6 +87,7 @@ <h1>
     </div>
     {% endif %}
 
+    {% block workflow %}
     <nav id="menu-bar">
       <ul class="row gap">
         <li class="row gap-small centered"><i class="icon-bin"></i><a href="{% url 'webview:suggestion:dismissed_suggestions' %}">Dismissed suggestions</a></li>
@@ -95,6 +96,7 @@ <h1>
         <li class="row gap-small centered"><i class="icon-github"></i><a href="{% url 'webview:issue_list' %}">Published issues</a></li>
       </ul>
     </nav>
+    {% endblock %}
 
     {% block layout %}
       <main id="page-content">

src/webview/templates/home_view.html

@@ -1,27 +1,48 @@
 {% extends "base.html" %}
 
+{% block workflow %}
+{% endblock %}
+
 {% block content %}
+{% load viewutils %}
 
 <article class="prose">
   <p>
-    The <strong>Nixpkgs Security Tracker</strong> is a web service for managing information on <em>vulnerabilities</em> in software distributed through <a href="https://github.com/nixos/nixpkgs">Nixpkgs and NixOS</a>.
-    It operates on the following distinctions:
+    The <strong>Nixpkgs Security Tracker</strong> is a web service for managing information on vulnerabilities in software distributed through <a href="https://github.com/nixos/nixpkgs">Nixpkgs and NixOS</a>.
+  </p>
+  <p>
+    It is intended to help with solving the <a href="https://en.wikipedia.org/wiki/Record_linkage" target="_blank">record linkage</a> problem of matching packages in the <a href="https://www.cve.org/" target="_blank">CVE database</a> and <a href="https://search.nixos.org/packages" target="_blank">Nixpkgs</a>.
   </p>
-  <ul>
-    <li>
-      <span class="inline-row gap-small centered"><i class="icon-inbox"></i><a href="{% url 'webview:suggestion:untriaged_suggestions' %}">Untriaged suggestions</a></span> are automatically generated matches between a <a href="https://www.cve.org/ResourcesSupport/Glossary#glossaryCVE">CVE</a> and Nixpkgs derivations.
-    </li>
-    <li>
+  <h2 class="heading">Workflow</h2>
+    <p>
+      <span class="inline-row gap-small centered"><i class="icon-inbox"></i><a href="{% url 'webview:suggestion:untriaged_suggestions' %}">Untriaged suggestions</a></span> are automatically generated matches between a <a href="https://www.cve.org/ResourcesSupport/Glossary#glossaryRecord">CVE Record</a> and Nixpkgs derivations.
+    </p>
+    <p>
       <span class="inline-row gap-small centered"><i class="icon-bin"></i><a href="{% url 'webview:suggestion:dismissed_suggestions' %}">Dismissed suggestions</a></span> are CVEs that already were classified by a human as <em>not affecting</em> Nixpkgs.
-    </li>
-    <li>
-      <span class="inline-row gap-small centered"><i class="icon-draft"></i><a href="{% url 'webview:suggestion:accepted_suggestions' %}">Accepted suggestions</a></span> are matches between a CVE and Nixpkgs attributes that were selected as <em>security relevant</em>.
-      They are slated to be published as a GitHub issue, but might need further refinement.
-    </li>
-    <li>
-      <span class="inline-row gap-small centered"><i class="icon-github"></i><a href="/issues">Published issues</a></span> have a persistent identifier and link to GitHub issues, which are used for notifications and coordinating mitigation.
-    </li>
-  <ul>
+    </p>
+    <p>
+      <span class="inline-row gap-small centered"><i class="icon-draft"></i><a href="{% url 'webview:suggestion:accepted_suggestions' %}">Accepted suggestions</a></span> are slated to be published, but might need further refinement.
+    </p>
+    <p>
+      <span class="inline-row gap-small centered"><i class="icon-github"></i><a href="/issues">Published issues</a></span> have a persistent identifier and link to <a href="{% gh_issues_url %}" target="_blank">GitHub issues</a>, where maintainers are notified and mitigation is coordinated.
+    </p>
+
+  <h2 class="heading">Contributors</h2>
+  <p>
+    <a href="https://github.com/NixOS/nixpkgs-committers/" target="_blank">Nixpkgs committers</a>
+    can edit suggestions to help the
+    <a href="https://github.com/orgs/nixos/teams/security" target="_blank">NixOS security team</a>
+    with triaging.
+  </p>
+  <p>
+    <a href="https://github.com/orgs/nixos/teams/nixpkgs-maintainers" target="_blank">Nixpkgs maintainers</a>
+    are encouraged to check their <a href="{% url 'webview:notifications:center' %}">notifications</a>.
+  </p>
+
+  <h2 class="heading">Users</h2>
+  <p>
+    If you use NixOS or otherwise rely on software from Nixpkgs, <a href="{% url 'webview:subscriptions:center' %}">subscribe to notifications</a> on published vulnerabilities.
+  </p>
 </article>
 
 {% endblock %}

src/webview/templates/issue_list.html

@@ -7,7 +7,7 @@ <h1 class="page-title row gap-small centered">{% status_icon "published" %}Publi
 
 <div class="prose">
   <p>
-    All published security issues are <a href="https://github.com/NixOS/nixpkgs/issues?q=is%3Aissue%20state%3Aopen%20label%3A%221.severity%3A%20security%22" target="_blank">tracked and resolved on GitHub</a>.
+  All published security issues are <a href="{% gh_issues_url %}" target="_blank">tracked and resolved on GitHub</a>.
   </p>
 </div>
 

src/webview/templatetags/viewutils.py

@@ -2,11 +2,12 @@
 import logging
 from collections.abc import ItemsView
 from typing import Any, TypedDict
-from urllib.parse import quote
+from urllib.parse import quote, urlencode
 
 from cvss import CVSS3
 from cvss.constants3 import METRICS_ABBREVIATIONS
 from django import template
+from django.conf import settings
 from django.template.context import Context
 
 from shared.listeners.cache_suggestions import CachedSuggestion, parse_drv_name
@@ -292,3 +293,11 @@ def maintainer_add(
     data: MaintainerAddContext,
 ) -> dict:
     return {"data": data}
+
+
+@register.simple_tag
+def gh_issues_url() -> str:
+    base = f"https://github.com/{settings.GH_ORGANIZATION}/{settings.GH_ISSUES_REPO}/issues"
+    labels = " ".join(f"label:{label!r}" for label in settings.GH_ISSUES_LABELS)
+    query = f"is:issue state:open {labels}".strip()
+    return f"{base}?{urlencode({'q': query})}"