Skip to content

docs: improve published release notes and upgrade guidance - #467

Merged
TheWitness merged 9 commits into
developfrom
docs/5.0-release-notes
Nov 20, 2026
Merged

TheWitness merged 9 commits into
developfrom
docs/5.0-release-notes

Conversation

@somethingwithproof

@somethingwithproof somethingwithproof commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Also refreshes the README against current source and published-release metadata, with the installation directory and compatibility requirements stated separately.

Adds focused release notes for all 12 published GitHub releases, with version-specific highlights, compatibility requirements, upgrade checks, linked contributor credits and comparison/history links. Preserves original detailed announcements in expandable sections and adds a release-history index linked from README and CHANGELOG.

Keeps 5.0 explicitly unreleased, with a separate published-release history through 4.2. Replaces the long 5.0 commit index with concise credits and selected commits, and adds workflow illustrations and upgrade decision tables.

Validation: checked local links, SVG XML, tag-specific compatibility metadata and original-announcement preservation; verified commit attribution against GitHub and matching live release descriptions. Documentation only.

Fixes #466

@somethingwithproof somethingwithproof changed the title docs: add 5.0 release notes and contributor credits docs: clarify release highlights, upgrades and contributor credits Nov 18, 2026
@somethingwithproof somethingwithproof changed the title docs: clarify release highlights, upgrades and contributor credits docs: improve published release notes and upgrade guidance Nov 18, 2026

@TheWitness TheWitness left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By default in the develop branch, all README.md files are displayed from the UI. This multi-tiered approach breaks that rendering. So, you should have first submitted a design proposal as to how we should be restructure the README.md files such that it is compatible with the Plugin Management interface prior to creating multiple pull request that are not compatible with that design intent.

@somethingwithproof

Copy link
Copy Markdown
Member Author

The READMEs I updated were inconsistent and outdated. I fixed an existing problem. If there’s something wrong with those changes, identify it so we can resolve it. This is routine maintenance.

Refs #466

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
Re-checked the documentation against INFO, setup.php, the settings
arrays, registered realms and CLI usage text, and fixed the statements
that did not match. Adds the realms, settings and command line tools
the README did not mention.

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
Plugin Management renders README.md and CHANGELOG.md from the release tag in a dialog, so relative links resolve against the Cacti server and return 404.

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
@somethingwithproof

Copy link
Copy Markdown
Member Author

Plugin Management fetches only README.md and CHANGELOG.md from the release tag and renders them with Parsedown, so the relative docs/ links would have 404'd in the plugin dialog. I've changed every link these PRs add to README.md or CHANGELOG.md to an absolute GitHub URL, and moved the release-notes links below the description so the dialog opens with the plugin overview. The same fix is pushed to the other open README PRs.

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>
@TheWitness

Copy link
Copy Markdown
Member

Thanks @somethingwithproof, when you click the revised links, are they opening in a new tab then?

@TheWitness TheWitness left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not safe as-is in the Cacti develop Plugins README dialog. In Cacti develop, the .pireadme handler calls displayFileDialog(), which fetches the Parsedown-rendered README and inserts the sanitized HTML into the jQuery UI dialog. That path does not add target="_blank" to links. Consequently, clicking the new links in README.md (for example, Source branch at line 33, and the release-history/workflow links) navigates the current tab away from Cacti and closes the dialog; the concern applies to both external and GitHub links. DOMPurify sanitization does not change this navigation behavior.

Please address the link behavior before merge, or ensure the Cacti dialog renders README anchors in a new tab (with rel="noopener"). Until then, users opening this README from Console > Configuration > Plugins can lose their current Cacti page by following a link.

@TheWitness
TheWitness force-pushed the docs/5.0-release-notes branch from 20e4c97 to 70a973b Compare November 20, 2026 13:33
Resolve CHANGELOG.md and RecommendationsTest.php conflicts.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@sonarqubecloud

Copy link
Copy Markdown

@TheWitness

Copy link
Copy Markdown
Member

Going to do a change on the Cacti side to work around this issue.

@TheWitness
TheWitness dismissed their stale review November 20, 2026 13:53

Going to do a change on the Cacti side to work around this issue.

@TheWitness
TheWitness merged commit 39d5d1a into develop Nov 20, 2026
11 checks passed
@TheWitness
TheWitness deleted the docs/5.0-release-notes branch November 20, 2026 14:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document 5.0 highlights, upgrade actions and contributor credits

3 participants