Add an upgrade-notes document in the repository collecting breaking changes across versions

[Fantu]

Is your feature request related to a problem? Please describe.

NSClient++ has no place in the repository that answers the single question every
upgrade starts with: what changes between the version I am running and the version
I am installing require me to do something, or silently change how my existing
configuration behaves?

The recent development pace makes this much more pressing: a lot of new checks,
fixes and behaviour changes across several releases in a short time (0.13.0 → 0.16.1
in roughly two months), so there are more versions to cross and more changes that can
bite. Those releases do contain genuinely good upgrade information — the "⚠️ Upgrade
notes" section at the bottom of the release notes — but it lives only in the GitHub
release body of each tag, so the number of places to consult grows with every release
while the answer stays scattered.

That said, the need does not come from the pace, it is only amplified by it. I have
been using NSClient++ for many years and the same difficulty was there when releases
were rarer and breaking changes fewer — arguably it is even easier to get caught
then, because a slow-moving project is exactly the one you install and forget. That
is the normal life of a monitoring agent: it is set up once, it works, nobody touches
it for months or years, and then someone upgrades it across a large version gap. At
that point it makes little difference whether the gap contains twenty releases or
two: what matters is whether the handful of changes that require intervention is
written down somewhere you can read in one go. So this would be worth having even if
development slowed down tomorrow — documenting breaking changes and significant
behaviour changes in a durable, versioned place seems to me a basic expectation for
any serious project, independently of how fast it moves.

Today that means:

• opening the GitHub releases page and reading every single release body one by one —
  every one of them, because the version number tells you nothing about what is safe
  to skip: a minor or patch-level bump is not a guarantee of "no breaking changes",
  and in practice substantial changes do show up there too. Some releases turn out to
  have no upgrade notes at all, but you only find that out by opening them. There is
  no shortcut: you read them all, or you risk missing exactly the one that matters;
• mentally merging the notes of N releases into one list, and hoping nothing was
  missed;
• doing it online — there is nothing in the source tarball, in the installed
  package, or on the documentation site that answers "what breaks if I jump from
  0.13.0 to 0.16.1?".

And getting it wrong has consequences of very different severity: the agent may not
work at all after the upgrade, or work only in part, or work while quietly producing
different results than before. In every case you find out afterwards, by debugging,
instead of before, by reading. I have come across changes of this kind over the years,
and I have had a hard time precisely because a document like the one I am asking for
did not exist: upgrading an installation left alone for a long time meant piecing
together, after the fact, what had changed and why something no longer worked as
before. So this is not something the recent releases created — they only make an old
gap easy to see.

A second problem: sometimes a breaking change only turns out to be one after the
release, when users hit it. The release body of an already published tag is
effectively frozen in practice — nobody re-reads a release they already installed —
so there is no good place to record "this change in 0.15.0 also affects X, do Y".

Describe the solution you'd like

A dedicated, version-ordered upgrade document maintained inside the repository —
e.g. UPGRADING.md at the top level (and/or exposed on the docs site under Setup,
so it is also reachable from nsclient.org).

Everything below is a suggestion, not a requirement — name, structure and level of
detail are entirely yours to decide; I only care that the information exists in the
repository in some readable form.

Name: UPGRADING.md is the most common convention, but UPGRADE_NOTES.md,
UPGRADING_NOTES.md or simply "Upgrade notes" as a docs page title would all work —
whatever reads best next to the existing README.md / SECURITY.md.

Shape:

• One section per version, newest first, each linking to the corresponding
  GitHub release for the full story.
• Only actionable content: breaking changes, changed defaults, silent behaviour
  changes, renamed/removed settings and options, packaging/layout changes. The value
  of this file is that it is short and can be read top-down.
• Each entry states what changed → what you must do, with the affected setting
  or module named explicitly, so it can be grepped (grep -i checknet UPGRADING.md).

Within each version it would help to split the entries into subsections, so that
someone upgrading across many versions can read only the first subsection of each and
still be safe. The criterion that seems to work best is not "how important is this"
but what it does to an existing installation that is upgraded unchanged:

1. Requires action — the existing configuration stops working, or works
   differently in a way you must correct: removed or renamed settings and options,
   changed defaults that apply to existing installs, security defaults that now refuse
   what used to be allowed, changed file/install layout. Nobody may skip this section.
2. Changes behaviour without requiring action — the configuration keeps working
   untouched, but the result is not identical: extra or renamed perfdata, different
   output or wording, a metric computed differently, a value that used to be literal
   and is now expanded. Nothing to fix, but worth knowing before the graphs or the
   alert thresholds start behaving differently.
3. (optional) New things you have to opt into — additions that change nothing
   until you enable them, but that are easy to mistake for a broken upgrade: a new
   module that is not loaded by default, a new option that defaults to off, a new
   check that returns UNKNOWN until configured. Strictly speaking these are not
   upgrade notes at all; the reason to keep a short list here is that they answer
   "why doesn't this new thing work after upgrading?" in the place people are already
   looking. This is the subsection I am least sure about — an actual list of new
   features definitely does not belong here (that is what the release notes and/or
   a changelog are for), and if it risks growing, a one-line pointer per version
   ("see the release notes for the new checks in this version") is probably better.

To make the difference concrete, using the existing 0.14.1 notes: "CheckNet
perfdata is now on by default" belongs in group 2 — an unchanged configuration
starts emitting perfdata it did not emit before — while "CheckSecurity is not
loaded by default" belongs in group 3, since CheckSecurity is a module added in
that release: nothing was disabled by the upgrade, it simply has to be enabled if you
want to use the new checks. Today both sit under the same "Upgrade notes" heading,
which is exactly the distinction the subsections would make.

An alternative (or complement) is a severity marker per item, e.g.
⚠️ action required / ℹ️ behaviour change / ✅ opt-in only. If the entries are
already grouped in subsections, the markers are probably redundant — either mechanism
alone should be enough.

Usage is then trivial: "I am on 0.13.0, I want 0.16.1" → read every section from the
top down to your version, and you have the complete list, offline, in the source you
just downloaded.

Two things that would make it noticeably more useful:

1. An ## Unreleased section at the top, updated by the PR that introduces the
   behaviour change, while the context is fresh. At release time that section is
   simply renamed to the version number — and it is also exactly the text to paste
   into the "⚠️ Upgrade notes" section of the GitHub release. This inverts today's
   flow (write it in the release body, and nowhere else) at essentially zero extra
   cost, and it makes it much harder to ship a breaking change with no note at all.

2. Allowing entries to be added retroactively to older versions, for breaking
   changes whose impact only became clear later (bug reports, regressions found
   afterwards). Marking them as added after the fact, e.g.
   _(note added 2026-08-14)_, keeps it honest. This is something a frozen GitHub
   release body cannot do.

Starting small is fine. There is no need to archaeologically reconstruct the
whole history: seeding the file with the releases that already have written upgrade
notes (0.13.0, 0.14.0, 0.14.1, 0.15.0, 0.16.0, 0.16.1) is mostly copy-paste of text
that already exists, and covers the versions people are realistically upgrading from
today. Older versions can be added opportunistically, when someone asks or when a
problem surfaces — the file gets more valuable over time without ever being a big
one-off effort.

Rough skeleton:

# Upgrading NSClient++

Read every section from the version you are running up to the version you are
installing. Only changes that require action or that change behaviour are listed;
see the release notes for the full changelog.

## Unreleased

### Requires action

- **<setting/module> …** what changed, and what you have to do.

## 0.16.1 — 2026-08-14 ([release notes](https://github.com/mickem/nscp/releases/tag/0.16.1))

### Requires action

- **Settings urls with a query string now actually send it.** A server relying on
  receiving the bare path will now see the parameters; check the receiving end before
  upgrading. The old cache file is migrated to the new query-aware name once on first
  start.
- **Building the docs on non-Windows needs an explicit flag:**
  `-DNSCP_BUILD_DOCS_HTML=ON`.

### Changes behaviour without requiring action

- **`${hostname}` is now expanded in configuration.** It used to be left in place as
  literal text by `expand_hostname`; it now expands everywhere that helper is used,
  including the submit clients' `hostname` setting.

### New things you have to opt into

- **`check_logfile` bookmarks.** Without `bookmark` / `max-lines` the check reads the
  whole file exactly as before and stores no position.
- **`run on startup`** is off by default; enabling it for the `default` schedule
  affects the whole fleet, see `startup window`.

## 0.14.1 — 2026-07-06 ([release notes](…))

### Changes behaviour without requiring action

- **CheckNet perfdata is now on by default.** Network checks emit performance data
  without an explicit `perf` syntax; graphs that showed nothing will start populating,
  and manually added perfdata may now be emitted twice.

### New things you have to opt into

- **`CheckSecurity` (new module) is not loaded by default.** Enable it before using
  the new checks: `nscp settings --active-module CheckSecurity`. Windows-only checks
  return UNKNOWN on other platforms.

---

Note: I briefly described it in Italian in a few minutes, then had Claude translate and explain it better, but unfortunately the result was terrible. I hope I fixed it enough in just over an hour.
The example parts are incomplete and may still contain errors because I checked more quickly and only corrected a couple of things.

[Fantu]

Furthermore, if you do this, I'd suggest adding the instructions in claude.md to the checks it run at the end of the changes you've made with Claude or had checked with it to update that document if necessary. If Claude do this when it have everything it need in context, there's a much higher chance that you'll get something right than a cursory check of everything when preparing the changelog for the new version.

[mickem]

This is very reasonable...
And we used to have this a long time ago in the actual docs, but I removed it as it was hard to know what "old was" if it is a log since the dawn of time it just grows longer and longer.
My thinking then was that you can read release notes.
But lately the release notes have become very long which I guess makes that harder so I guess we need a compressed place again...
I will have a look around at where to host it, perhaps a section on the web page is a better place than to have it in the docs...

[Fantu]

Not only on the site and in another repo, but possibly also on the site instead.
I think it needs to be in the repository so it can be included in the Debian package (and also included in any installation in general).
The fact that there are so many breaking changes worries me. I fear that many users don't use it because of this, and it could greatly discourage implementation in Linux distros.
Thinking about Debian packaging, for example, I was thinking that having a package that can "break" when upgrading from one version to another many times isn't good, and so I'll have to find a workaround to prevent it from failing to boot after installation due to configuration issues (it would block the entire upgrade of Debian).
Usually, a debian/NEWS file would be used for important notices, such as configuration incompatibilities, but in nscp I think there are too many, even just for the most important ones. Normally, d/NEWS is something that is used very rarely; in many years, out of hundreds of uploads (maybe over a thousand by now), I think I've only used it three times.

[mickem]

Hmm...

I would say there are little breaking changes and most are exotic and bug fixes as in will not affect many users...
There have been some tightening of security (which are mandatory) but what changes is it that you feel are problematic?

Just to verify my thesis here are all breaking changes (behaviour changes that impacts end users) in the last 12:ish months:

0.15.0:

• check_process delta=true requires config option.

This is breaking and could have been avoided really...

0.14.1:

• CheckNet perfdata is now on by default.

This I would say is a bugfix

0.14.0:

• The web server refuses to run unencrypted by default.

Should not impact actual users as a certificate is generated by default

• Some linux changes to make it run on linux

Before this time I would say running NSClient++ on linux was an adventure

0.12.6:

• Undocumented path overrides moved.

Should not impact end users as it was a "hidden feature"

0.12.4

• Fixed API breaking introduced in 0.12.3 for Icinga

Fixes an issue (so a good thing)

0.12.3:

• Empty allowed hosts now rejects all connections.
• check_nt (NSClientServer) defaults to ssl = true.
• Fixed a number of security issues in the WEBServer (1 impacting icinga)
• Security fix: CheckExternalScripts: The old "split-on-space" parser has been removed.

Above here are mandatory security issues

• Swapped to "local time" by default instead of UTC.

Breaking change, and this one I spent a long time pondering if I should do or not as I know it is a breaking change

• Fixed warn= / crit= and count issues

This is a positive change so likely not breaking any existing usecases

• Bugfix in check_service: delayed is no longer reported for non-auto services.
• Bugfix in check_process is now case-insensitive. A rule that intentionally matched only an exact casing will
• Bugfix check_service: ${desc} no longer returns the literal TODO. Use the real display name.
• Bugfix: check_service: perf-syntax=none actually suppresses perfdata.
• Bugfix: check_files — corner cases fixed

All of these are positive change i.e. make the check behave as it it should have been al along

• Documentation reorganisation

Does not impact usage

0.11.25:

• Installer issue: If you use ALLOW_CONFIGURATION when upgrading from an old version the configuration might be deleted.

Likely only impacts very few users

[Fantu]

I think the update notes are necessary.

Regarding breaking changes, I haven't done a thorough analysis.

I seem to recall that I'd already seen the problem years ago and since then I'd "set up" a way to avoid/limit the problems.
Then I left it untouched for a long time, and when I reworked it, mainly with updates from 0.5.x to 0.9.x (if I remember correctly), I had redone the configuration files, so I avoided potential problems.
A significant problem fairly recently was deleting the configuration ini on upgrade (which I didn't do with frequent updates). The first time I had this, I had to restore it from a backup, then I always backed up the file before proceeding, and finally you solved it.

Years ago, I saw several reviews that described this project as very useful but complicated for configuration management. Then, when I was considering finding something different, I saw others complaining about security issues due to obsolete protocols (which you later fixed), and there were also those who used it extensively on tens of thousands of devices or more, who thought NSCP was being abandoned and had created other similar software that was compatible with the configuration.
At that time (the article was already "old" when I read 1 years ago or more if I'm not wrong, I saw that development had resumed, so I continued using NSCP.

EDIT:
Furthermore, recently, given the continuous updates to improve monitoring with recent additions, bug fixes, etc., I've created internal documentation with ready-made commands, in which I make device-specific changes only with some, and I've also noted any other necessary additions/changes to the configuration outside of the commands (but more specific to my needs). I'll definitely need my internal update documentation now that I'm using nscp more, and also because the checks used are increasingly numerous and there are more differences between devices, so always redoing from a "cookie cutter" risks wasting too much time in the long run.

In any case, from this, I thought having an upgrade notes in the repository would be very useful for the project and its users.

[mickem]

Agreed upgrade notes are needed...