From 56c36b9f7aa7fcd753eb4edf68cd989287185965 Mon Sep 17 00:00:00 2001
From: Arthur Bols <arthur@bols.dev>
Date: Aug 01 2024 16:14:47 +0000
Subject: Add shell completions section


---

diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc
index c75834e..5a366c7 100644
--- a/guidelines/modules/ROOT/nav.adoc
+++ b/guidelines/modules/ROOT/nav.adoc
@@ -79,6 +79,7 @@
 ** xref:LibreOfficeExtensions.adoc[LibreOffice Extensions]
 ** xref:MinGW.adoc[MinGW]
 ** xref:MPI.adoc[MPI]
+** xref:ShellCompletions.adoc[Shell Completions]
 ** xref:SugarActivityGuidelines.adoc[Sugar activities]
 ** xref:Web_Assets.adoc[Web Assets]
 ** xref:WordPress_plugin_packaging_guidelines.adoc[WordPress extensions]
diff --git a/guidelines/modules/ROOT/pages/ShellCompletions.adoc b/guidelines/modules/ROOT/pages/ShellCompletions.adoc
new file mode 100644
index 0000000..e9cf43c
--- /dev/null
+++ b/guidelines/modules/ROOT/pages/ShellCompletions.adoc
@@ -0,0 +1,48 @@
+= Shell Completions
+
+Shell completions are command line completions for a specific shell,
+such as Bash, fish or Zsh.
+
+== RPM Macros
+
+The following macros *MUST* be used instead of hardcoding paths.
+
+[cols=",",options="header"]
+|======================================================================
+| macro                     | definition
+| +%{bash_completions_dir}+ | +%{_datadir}/bash-completion/completions+
+| +%{fish_completions_dir}+ | +%{_datadir}/fish/vendor_completions.d+
+| +%{zsh_completions_dir}+  | +%{_datadir}/zsh/site-functions+
+|======================================================================
+
+
+== Shell Completions Packaging
+
+Shell completion files *MUST* use standard file permissions (0644).
+
+=== Example of shell completions packaging
+
+[source, rpm-spec]
+----
+Name: foo
+...
+
+%install
+...
+
+# Bash completion
+install -Dpm 0644 foo.bash -t %{buildroot}%{bash_completions_dir}
+
+# Fish completion
+install -Dpm 0644 foo.fish -t %{buildroot}%{fish_completions_dir}
+
+# Zsh completion
+install -Dpm 0644 _foo -t     %{buildroot}%{zsh_completions_dir}
+...
+
+%files
+%{bash_completions_dir}/foo.bash
+%{fish_completions_dir}/foo.fish
+%{zsh_completions_dir}/_foo
+
+----