From 3d79d6dea96f78614592715073ab03b09d4571ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotr=20W=C3=B3jcik?= <chocimier@tlen.pl>
Date: Wed, 5 Jan 2022 21:33:24 +0100
Subject: [PATCH] Manual.md: document renaming a package

---
 Manual.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Manual.md b/Manual.md
index 90c8dcb65f8..d9081d023d1 100644
--- a/Manual.md
+++ b/Manual.md
@@ -42,6 +42,7 @@ packages for XBPS, the `Void Linux` native packaging system.
 	* [Go packages](#pkgs_go)
 	* [Haskell packages](#pkgs_haskell)
 	* [Font packages](#pkgs_font)
+	* [Renaming a package](#pkg_rename)
 	* [Removing a package](#pkg_remove)
 	* [XBPS Triggers](#xbps_triggers)
 		* [appstream-cache](#triggers_appstream_cache)
@@ -1659,6 +1660,18 @@ cache during the install/removal of the package
 - `font_dirs`: which should be set to the directory where the package
 installs its fonts
 
+<a id="pkg_rename"></a>
+### Renaming a package
+
+- Create empty package of old name, depending on new package. This is
+necessary to provide updates to systems where old package is already
+installed. This should be a subpackage of new one, except when version
+number of new package decreased: then create a separate template using
+old version and increased revision.
+- Edit references to package in other templates and common/shlibs.
+- Don't set `replaces=`, it can result in removing both packages from
+systems by xbps.
+
 <a id="pkg_remove"></a>
 ### Removing a package