From ae87721626245f449c12cae4a441cf9a1ddb1a29 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Fri, 23 May 2025 18:14:30 +0200 Subject: [PATCH 1/2] nixos-render-docs: make error message on broken redirects less verbose before, we were showing (almost) the same set of options twice in case of renaming an identifier, which is confusing and obsucres the recommendation. after this change we also show the recommendation in a much more frequent case, when contributors add a new identifier. --- .../src/nixos_render_docs/redirects.py | 46 ++++++------------- 1 file changed, 13 insertions(+), 33 deletions(-) diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/redirects.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/redirects.py index 1a891a1af238..06049497344c 100644 --- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/redirects.py +++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/redirects.py @@ -28,8 +28,7 @@ Identifiers must not be identical to any historical location's anchor of the sam The following identifiers violate this rule: - {"\n - ".join(self.conflicting_anchors)} - This can break links or redirects. If you added new content, choose a different identifier. -""") + This can break links or redirects. If you added new content, choose a different identifier.""") if self.divergent_redirects: error_messages.append(f""" All historical content locations must correspond to exactly one identifier. @@ -37,8 +36,7 @@ All historical content locations must correspond to exactly one identifier. - {"\n - ".join(self.divergent_redirects)} It leads to inconsistent behavior depending on which redirect is applied. - Please update doc/redirects.json or nixos/doc/manual/redirects.json! -""") + Please update doc/redirects.json or nixos/doc/manual/redirects.json!""") if self.identifiers_missing_current_outpath: error_messages.append(f""" The first element of an identifier's redirects list must denote its current location. @@ -46,14 +44,18 @@ The first element of an identifier's redirects list must denote its current loca - {"\n - ".join(self.identifiers_missing_current_outpath)} If you moved content, add its new location as the first element of the redirects mapping. - Please update doc/redirects.json or nixos/doc/manual/redirects.json! -""") + Please update doc/redirects.json or nixos/doc/manual/redirects.json!""") if self.identifiers_without_redirects: error_messages.append(f""" Identifiers present in the source must have a mapping in the redirects file. - - {"\n - ".join(self.identifiers_without_redirects)} - - This can happen when an identifier was added or renamed. + - {"\n - ".join(self.identifiers_without_redirects)}""") + if self.orphan_identifiers: + error_messages.append(f""" +Keys of the redirects mapping must correspond to some identifier in the source. + - {"\n - ".join(self.orphan_identifiers)}""") + if self.identifiers_without_redirects or self.orphan_identifiers or self.identifiers_missing_current_outpath: + error_messages.append(f""" +This can happen when an identifier was added, renamed, or removed. Added new content? redirects add-content ❬identifier❭ ❬path❭ @@ -67,31 +69,9 @@ Identifiers present in the source must have a mapping in the redirects file. Removed content? Redirect to alternatives or relevant release notes. redirects remove-and-redirect ❬identifier❭ ❬target-identifier❭ - Note that you need to run `nix-shell doc` or `nix-shell nixos/doc/manual` to be able to run this command. + NOTE: Run `nix-shell doc` or `nix-shell nixos/doc/manual` to make this command available. """) - if self.orphan_identifiers: - error_messages.append(f""" -Keys of the redirects mapping must correspond to some identifier in the source. - - {"\n - ".join(self.orphan_identifiers)} - - This can happen when an identifier was removed or renamed. - - Added new content? - redirects add-content ❬identifier❭ ❬path❭ - - Moved existing content to a different output path? - redirects move-content ❬identifier❭ ❬path❭ - - Renamed existing identifiers? - redirects rename-identifier ❬old-identifier❭ ❬new-identifier❭ - - Removed content? (good for redirecting deprecations to new content or release notes) - redirects remove-and-redirect ❬identifier❭ ❬target-identifier❭ - - Note that you need to run `nix-shell doc` or `nix-shell nixos/doc/manual` to be able to run this command. -""") - - error_messages.append("NOTE: If your Manual build passes locally and you see this message in CI, you probably need a rebase.") + error_messages.append("NOTE: If your build passes locally and you see this message in CI, you probably need a rebase.") return "\n".join(error_messages) From 9225715a2320abf8db95cc2e01ae771db3c2929f Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Wed, 28 May 2025 19:56:54 +0200 Subject: [PATCH 2/2] nixos-render-docs: Suggest redirects is a command --- .../nixos-render-docs/src/nixos_render_docs/redirects.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/redirects.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/redirects.py index 06049497344c..ba338edeb17a 100644 --- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/redirects.py +++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/redirects.py @@ -58,16 +58,16 @@ Keys of the redirects mapping must correspond to some identifier in the source. This can happen when an identifier was added, renamed, or removed. Added new content? - redirects add-content ❬identifier❭ ❬path❭ + $ redirects add-content ❬identifier❭ ❬path❭ Moved existing content to a different output path? - redirects move-content ❬identifier❭ ❬path❭ + $ redirects move-content ❬identifier❭ ❬path❭ Renamed existing identifiers? - redirects rename-identifier ❬old-identifier❭ ❬new-identifier❭ + $ redirects rename-identifier ❬old-identifier❭ ❬new-identifier❭ Removed content? Redirect to alternatives or relevant release notes. - redirects remove-and-redirect ❬identifier❭ ❬target-identifier❭ + $ redirects remove-and-redirect ❬identifier❭ ❬target-identifier❭ NOTE: Run `nix-shell doc` or `nix-shell nixos/doc/manual` to make this command available. """)