Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Explain safe retesting and contesting an issue closure

pulse-triage[bot]de4751f25a17
diff --git a/docs/AI_TRANSPARENCY.md b/docs/AI_TRANSPARENCY.md
index 4779cd64b7..14959058b0 100644
--- a/docs/AI_TRANSPARENCY.md
+++ b/docs/AI_TRANSPARENCY.md
@@ -79,6 +79,34 @@ released source, and ask for a retest when appropriate. See the
[published releases](https://github.com/rcourtman/Pulse/releases) for available
versions; a source commit or a passing test alone does not establish availability.
+## Issue resolution and retesting
+
+A bug is resolved when the reporter confirms recovery, or the maintainer
+reproduces the correction with no reported symptom left unresolved. A working
+workaround, one recovered screen or a merged fix does not settle every part of
+a mixed report. Other dispositions, such as a duplicate, need their own
+explanation; a feature request's demand-ledger entry is not an implemented feature.
+
+After a fix for every reported symptom ships in a stable release, the maintainer
+names that version and asks for a retest in the original issue. That reply says
+the issue will be closed after 14 days without a reply and can be reopened.
+The 14 days start with that stable-release retest reply, not the fix commit,
+a beta or a release candidate. Only retest when it is safe; do not repeat an
+outage, update or backup just to answer.
+
+If neither the reporter nor another person reports the same problem during
+those 14 days, the issue may be closed with a note and the
+`closed-needs-retest-timeout` label. This is a retest timeout, **not confirmed
+resolution**. It does not apply to feature requests, issues labelled
+`needs-human`, or reports with an unfixed or unexplained symptom.
+
+If the problem persists, or a close missed part of the report, comment on the
+original issue rather than filing it again. Say which symptom remains and give
+the version already observed, with any relevant [locally reviewed, redacted
+evidence](TROUBLESHOOTING.md#collect-diagnostics-safely); unknown details are
+valid and credentials stay private. Credible continuing failures or a mistaken
+close are grounds to reopen the issue, not evidence to dismiss because it was closed.
+
## Authority and responsibility
The automated maintainer owns ordinary maintenance and public Pulse issue
diff --git a/frontend-modern/public/docs/AI_TRANSPARENCY.md b/frontend-modern/public/docs/AI_TRANSPARENCY.md
index 4779cd64b7..14959058b0 100644
--- a/frontend-modern/public/docs/AI_TRANSPARENCY.md
+++ b/frontend-modern/public/docs/AI_TRANSPARENCY.md
@@ -79,6 +79,34 @@ released source, and ask for a retest when appropriate. See the
[published releases](https://github.com/rcourtman/Pulse/releases) for available
versions; a source commit or a passing test alone does not establish availability.
+## Issue resolution and retesting
+
+A bug is resolved when the reporter confirms recovery, or the maintainer
+reproduces the correction with no reported symptom left unresolved. A working
+workaround, one recovered screen or a merged fix does not settle every part of
+a mixed report. Other dispositions, such as a duplicate, need their own
+explanation; a feature request's demand-ledger entry is not an implemented feature.
+
+After a fix for every reported symptom ships in a stable release, the maintainer
+names that version and asks for a retest in the original issue. That reply says
+the issue will be closed after 14 days without a reply and can be reopened.
+The 14 days start with that stable-release retest reply, not the fix commit,
+a beta or a release candidate. Only retest when it is safe; do not repeat an
+outage, update or backup just to answer.
+
+If neither the reporter nor another person reports the same problem during
+those 14 days, the issue may be closed with a note and the
+`closed-needs-retest-timeout` label. This is a retest timeout, **not confirmed
+resolution**. It does not apply to feature requests, issues labelled
+`needs-human`, or reports with an unfixed or unexplained symptom.
+
+If the problem persists, or a close missed part of the report, comment on the
+original issue rather than filing it again. Say which symptom remains and give
+the version already observed, with any relevant [locally reviewed, redacted
+evidence](TROUBLESHOOTING.md#collect-diagnostics-safely); unknown details are
+valid and credentials stay private. Credible continuing failures or a mistaken
+close are grounds to reopen the issue, not evidence to dismiss because it was closed.
+
## Authority and responsibility
The automated maintainer owns ordinary maintenance and public Pulse issue
diff --git a/frontend-modern/src/features/docs/__tests__/issueFollowThroughGuide.test.ts b/frontend-modern/src/features/docs/__tests__/issueFollowThroughGuide.test.ts
new file mode 100644
index 0000000000..f57a33b721
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/issueFollowThroughGuide.test.ts
@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown, stripLeadingTitle } from '../docMarkdown';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const shippedDocs = path.join(repoRoot, 'frontend-modern/public/docs');
+const source = readFileSync(path.join(shippedDocs, 'AI_TRANSPARENCY.md'), 'utf8');
+
+function renderGuide(name: string, markdown: string): HTMLElement {
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(stripLeadingTitle(markdown), name);
+ return article;
+}
+
+function followThrough(): HTMLElement {
+ const article = renderGuide('AI_TRANSPARENCY', source);
+ const heading = article.querySelector('#issue-resolution-and-retesting');
+ expect(heading?.tagName).toBe('H2');
+ const section = document.createElement('section');
+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {
+ if (next.tagName === 'H2') break;
+ section.appendChild(next.cloneNode(true));
+ }
+ return section;
+}
+
+const prose = (element: HTMLElement): string =>
+ (element.textContent ?? '').replace(/\s+/g, ' ').trim();
+
+describe('public issue follow-through guidance', () => {
+ it('keeps resolution, stable-release retest and timeout distinct in rendered paragraphs', () => {
+ const paragraphs = followThrough().querySelectorAll('p');
+ expect(paragraphs).toHaveLength(4);
+ expect(prose(paragraphs[0])).toContain('no reported symptom left unresolved');
+ expect(prose(paragraphs[1])).toContain('start with that stable-release retest reply');
+ expect(prose(paragraphs[1])).toContain('not the fix commit, a beta or a release candidate');
+ const emphasis = paragraphs[2].querySelector('strong');
+ expect(emphasis).not.toBeNull();
+ expect(prose(emphasis!)).toBe('not confirmed resolution');
+ expect(prose(paragraphs[2])).toContain('neither the reporter nor another person');
+ expect(prose(paragraphs[2])).toContain('an unfixed or unexplained symptom');
+ });
+
+ it('keeps the existing issue and safe evidence route usable without new collection', () => {
+ const section = followThrough();
+ expect(prose(section)).toContain('original issue rather than filing it again');
+ expect(prose(section)).toContain('unknown details are valid and credentials stay private');
+ expect(prose(section)).toContain('do not repeat an outage, update or backup');
+ expect(section.querySelector('pre, form, input, button')).toBeNull();
+ const link = section.querySelector('a');
+ expect(link?.getAttribute('href')).toBe('/docs/TROUBLESHOOTING#collect-diagnostics-safely');
+ expect(link?.hasAttribute('data-doc-link')).toBe(true);
+ expect(link?.hasAttribute('target')).toBe(false);
+ const target = renderGuide(
+ 'TROUBLESHOOTING',
+ readFileSync(path.join(shippedDocs, 'TROUBLESHOOTING.md'), 'utf8'),
+ );
+ expect(target.querySelector('#collect-diagnostics-safely')?.tagName).toBe('H3');
+ });
+
+ it('ships the same explanation at the standing triage footer destination', () => {
+ expect(source).toBe(readFileSync(path.join(repoRoot, 'docs/AI_TRANSPARENCY.md'), 'utf8'));
+ const article = renderGuide('AI_TRANSPARENCY', source);
+ expect(article.querySelector('#how-changes-land-and-ship')).not.toBeNull();
+ expect(article.querySelector('#authority-and-responsibility')).not.toBeNull();
+ });
+});
diff --git a/scripts/tests/test_transparency_docs.py b/scripts/tests/test_transparency_docs.py
index a489b55f01..95ab982535 100644
--- a/scripts/tests/test_transparency_docs.py
+++ b/scripts/tests/test_transparency_docs.py
@@ -60,6 +60,44 @@ class TransparencyDocsTest(unittest.TestCase):
self.assertNotIn("Automated support replies are sent", text)
self.assertIn("[topic-integrity triage contract](ISSUE_TRIAGE.md)", text)
+ def test_resolution_needs_every_reported_symptom_not_a_component_pass(self):
+ for path, text in self.documents():
+ with self.subTest(document=path):
+ self.assertIn("reporter confirms recovery", text)
+ self.assertIn("no reported symptom left unresolved", text)
+ self.assertIn("one recovered screen or a merged fix", text)
+ self.assertIn("duplicate, need their own explanation", text)
+ self.assertIn("demand-ledger entry is not an implemented feature", text)
+
+ def test_timeout_starts_with_containing_stable_release_contact(self):
+ for path, text in self.documents():
+ with self.subTest(document=path):
+ self.assertIn("fix for every reported symptom ships in a stable release", text)
+ self.assertIn("closed after 14 days without a reply and can be reopened", text)
+ self.assertIn("start with that stable-release retest reply", text)
+ self.assertIn("not the fix commit, a beta or a release candidate", text)
+ self.assertIn("neither the reporter nor another person reports the same problem", text)
+
+ def test_timeout_is_not_confirmed_resolution_and_has_explicit_exclusions(self):
+ for path, text in self.documents():
+ with self.subTest(document=path):
+ self.assertIn("`closed-needs-retest-timeout` label", text)
+ self.assertIn("**not confirmed resolution**", text)
+ self.assertIn("does not apply to feature requests", text)
+ self.assertIn("issues labelled `needs-human`", text)
+ self.assertIn("an unfixed or unexplained symptom", text)
+
+ def test_contesting_a_close_preserves_the_report_and_safe_existing_evidence(self):
+ for path, text in self.documents():
+ with self.subTest(document=path):
+ self.assertIn("original issue rather than filing it again", text)
+ self.assertIn("which symptom remains", text)
+ self.assertIn("version already observed", text)
+ self.assertIn("unknown details are valid and credentials stay private", text)
+ self.assertIn("do not repeat an outage, update or backup", text)
+ self.assertIn("grounds to reopen the issue", text)
+ self.assertIn("TROUBLESHOOTING.md#collect-diagnostics-safely", text)
+
def test_standing_authority_preserves_review_and_mechanical_releases(self):
for path, text in self.documents():
with self.subTest(document=path):