document/orga(Contributor/How-to/review): from recent discussions

manuals/Contributor.md

@@ -3,4 +3,14 @@
 - Version: @NGIPKGS_VERSION@
 - Revision: @NGIPKGS_REVISION@
 
-ToDo
+```{toctree}
+Contributor/How_to/use/NGIpkgs_Contributor_s_Manual.md
+```
+
+```{toctree}
+Contributor/Exercise_to.md
+Contributor/How_to.md
+Contributor/Why_to.md
+Contributor/What_is.md
+Contributor/Release.md
+```

manuals/Contributor/Exercise_to.md

@@ -0,0 +1,5 @@
+{#Contributor_Exercise_to}
+# Tutorials for contributors
+
+While tutorials on Nix in general belong to [nix.dev/tutorials](https://nix.dev/tutorials/),
+the following exercises cover complementary topics arising while crafting NGIpkgs.

manuals/Contributor/How_to.md

@@ -0,0 +1,9 @@
+{#Contributor_How_to}
+# Recipes for contributors
+
+While generic how-to guides on Nix belong to [nix.dev/guides](https://nix.dev/guides/),
+the following recipes cover complementary topics arising while crafting NGIpkgs.
+
+```{toctree}
+How_to/review.md
+```

manuals/Contributor/How_to/review.md

@@ -0,0 +1,23 @@
+{#Contributor_How_to_review}
+# How to review?
+
+## With a trivial or blocking issue
+Use the PR's conversation page to do it.
+
+## With a non-trivial or non-blocking issue
+[Open a new issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) referencing it in:
+- the conversation of the PR,
+- any relevant parent issue.
+
+## With a trivial suggestion
+Whenever you think it makes sense, use Github's Web suggestion mechanism,
+making use of "Add suggestion to batch".
+
+## With a non-trivial suggestion
+Put your work in new commits stacked upon the PR's author (not `main`),
+and open a new PR directed at the PR author's own repository.
+Branches of <https://github.com/ngi-nix/ngipkgs> are currently not used for such contributions.
+
+## Without hurting people
+- <https://www.contributor-covenant.org/translations/>
+- <https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/code-review-antipatterns/>

manuals/Contributor/How_to/use/NGIpkgs_Contributor_s_Manual.md

@@ -0,0 +1,10 @@
+{#Contributor_How_to_use_NGIpkgs_Contributor_s_Manual}
+# How to use NGIpkgs Contributor's Manual?
+
+To learn how to contribute to NGIpkgs:
+- let yourself be guided with the [Tutorials for contributors](#Contributor_Exercise_to),
+- or browse and ponder the [Explanations for contributors](#Contributor_Why_to).
+
+To practice your craft by contributing to NGIpkgs:
+- let yourself be guided with the [Recipes for contributors](#Contributor_How_to),
+- or browse and ponder the [Descriptions for contributors](#Contributor_What_is).

manuals/Contributor/Release.md

@@ -0,0 +1,9 @@
+{#Contributor_Release}
+# Release Notes for contributors
+
+This section lists the release notes concerning contributors to NGIpkgs,
+for each stable version of NGIpkgs and current unstable revision.
+
+```{toctree}
+Release/NGIpkgs.md
+```

manuals/Contributor/Release/NGIpkgs.md

@@ -0,0 +1,6 @@
+{#Contributor_Release_NGIpkgs}
+# Release notes for contributors to NGIpkgs
+
+```{toctree}
+NGIpkgs/26.05.md
+```

manuals/Contributor/Release/NGIpkgs/26.05.md

@@ -0,0 +1,35 @@
+{#Contributor_Release_NGIpkgs_26_05}
+# Release notes for users of NGIpkgs 26.05 (2026.05/??)
+
+{#Contributor_Release_NGIpkgs_26_05_Highlights}
+## Highlights
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+- Create the first release note entry in this section!
+
+{#Contributor_Release_NGIpkgs_26_05_New_Packages}
+## New Packages
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+{#Contributor_Release_NGIpkgs_26_05_New_Modules}
+## New Modules
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+- Create the first release note entry in this section!
+
+{#Contributor_Release_NGIpkgs_26_05_Backward_Incompatibilities}
+## Backward Incompatibilities
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+- Create the first release note entry in this section!
+
+{#Contributor_Release_NGIpkgs_26_05_Other_Notable_Changes}
+## Other Notable Changes
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+- Create the first release note entry in this section!

manuals/Contributor/What_is.md

@@ -0,0 +1,8 @@
+{#Contributor_What_is}
+# Descriptions for contributors
+
+While descriptions pertaining to Nix in general belong to [nix.dev/reference](https://nix.dev/reference/),
+the following descriptions cover complementary materials for crafting NGIpkgs.
+
+```{toctree}
+```

manuals/Contributor/Why_to.md

@@ -0,0 +1,8 @@
+{#Contributor_Why_to}
+# Explanations for contributors
+
+While explanations pertaining to Nix in general belong to [nix.dev/concepts](https://nix.dev/concepts/),
+the following explanations cover complementary topics arising while crafting NGIpkgs.
+
+```{toctree}
+```

manuals/User.md

@@ -3,4 +3,17 @@
 - Version: @NGIPKGS_VERSION@
 - Revision: @NGIPKGS_REVISION@
 
-ToDo
+```{toctree}
+User/What_is/Nix@NGI.md
+User/What_is/NGIpkgs.md
+User/Why_to/install/NGIpkgs.md
+User/How_to/use/NGIpkgs_User_s_Manual.md
+```
+
+```{toctree}
+User/Exercise_to.md
+User/How_to.md
+User/Why_to.md
+User/What_is.md
+User/Release.md
+```

manuals/User/Exercise_to.md

@@ -0,0 +1,5 @@
+{#User_Exercise_to}
+# Tutorials for users
+
+```{toctree}
+```

manuals/User/How_to.md

@@ -0,0 +1,6 @@
+{#User_How_to}
+# Recipes for users
+
+```{toctree}
+How_to/install.md
+```

manuals/User/How_to/install.md

@@ -0,0 +1,7 @@
+{#User_How_to_install}
+# How to install?
+
+```{toctree}
+install/NGIpkgs.md
+install/Nix.md
+```

manuals/User/How_to/install/NGIpkgs.md

@@ -0,0 +1,7 @@
+{#User_How_to_install_NGIpkgs}
+# How to install NGIpkgs?
+
+```{toctree}
+NGIpkgs/using_cachix.md
+NGIpkgs/using_a_flake.nix.md
+```

manuals/User/How_to/install/NGIpkgs/using_a_flake.nix.md

@@ -0,0 +1,26 @@
+{#User_How_to_install_NGIpkgs_using_a_flake_nix}
+# How to install NGIpkgs using a `flake.nix`?
+
+You can insert this input in your `flake.nix`:
+```nix
+inputs.NGIpkgs.url = "github:ngi-nix/ngipkgs";
+```
+
+To avoid building dependencies of NGIpkgs' packages and services,
+you may ask users of your `flake.nix` to enable NGIpkgs' public build cache,
+by inserting this in your `flake.nix`:
+```nix
+nixConfig = {
+  extra-substituters = [ "https://ngi.cachix.org" ];
+  extra-trusted-public-keys = [ "ngi.cachix.org-1:n+CAL72ROC3qQuLxIHpV+Tw5t42WhXmMhprAGkRSrOw=" ];
+```
+
+If you want to accept such configuration from `flake.nix` automatically,
+you can add this setting in your NixOS configuration:
+```nix
+nix.settings.accept-flake-config = true;
+```
+
+If, when prompted, you trusted permanently that `nixConfig`,
+you can still revert your trust by editing a file usually
+located at `~/.local/share/nix/trusted-settings.json`.

manuals/User/How_to/install/NGIpkgs/using_cachix.md

@@ -0,0 +1,13 @@
+{#User_How_to_install_NGIpkgs_using_cachix}
+# How to install NGIpkgs using `cachix`?
+
+For your convenience, you may enable NGIpkgs' public build cache,
+either imperatively by using [cachix](https://www.cachix.org):
+```bash
+cachix use ngi
+```
+
+You can revert this trust with:
+```bash
+cachix remove ngi
+```

manuals/User/How_to/install/Nix.md

@@ -0,0 +1,15 @@
+{#User_How_to_install_Nix}
+# How to install Nix?
+
+Nix-the-language has multiple implementations:
+
+- [CppNix](https://nixos.org/download/) is the original implementation that is the most widely used.
+  This is the main implementation supported by NGIpkgs.
+  If in doubt install this.
+
+- [Lix](https://docs.lix.systems/manual/lix/stable/installation/supported-platforms.html)
+  is an alternative implementation that maintain some level of compatibility with `CppNix`,
+  and thus may work well on NGIpkgs.
+
+- [Tvix](https://tvix.dev/)
+  is alternative implementation that is not (yet) supported by NGIpkgs.

manuals/User/How_to/use/NGIpkgs_User_s_Manual.md

@@ -0,0 +1,10 @@
+{#User_How_to_use_NGIpkgs_User_s_Manual}
+# How to use NGIpkgs User's Manual?
+
+To learn how to use NGIpkgs:
+- let yourself be guided with the [Tutorials for users](#User_Exercise_to),
+- or browse and ponder the [Explanations for users](#User_Why_to).
+
+To practice your craft by using NGIpkgs:
+- let yourself be guided with the [Recipes for users](#User_How_to),
+- or browse and ponder the [Descriptions for users](#User_What_is).

manuals/User/Release.md

@@ -0,0 +1,9 @@
+{#User_Release}
+# Release Notes for users
+
+This section lists the release notes concerning users of NGIpkgs,
+for each stable version of NGIpkgs and current unstable revision.
+
+```{toctree}
+Release/NGIpkgs.md
+```

manuals/User/Release/NGIpkgs.md

@@ -0,0 +1,6 @@
+{#User_Release_NGIpkgs}
+# Release notes for users of NGIpkgs
+
+```{toctree}
+NGIpkgs/26.05.md
+```

manuals/User/Release/NGIpkgs/26.05.md

@@ -0,0 +1,35 @@
+{#User_Release_NGIpkgs_26_05}
+# Release notes for contributors to NGIpkgs 26.05 (2026.05/??)
+
+{#User_Release_NGIpkgs_26_05_Highlights}
+## Highlights
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+- Create the first release note entry in this section!
+
+{#User_Release_NGIpkgs_26_05_New_Packages}
+## New Packages
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+{#User_Release_NGIpkgs_26_05_New_Modules}
+## New Modules
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+- Create the first release note entry in this section!
+
+{#User_Release_NGIpkgs_26_05_Backward_Incompatibilities}
+## Backward Incompatibilities
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+- Create the first release note entry in this section!
+
+{#User_Release_NGIpkgs_26_05_Other_Notable_Changes}
+## Other Notable Changes
+
+<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. -->
+
+- Create the first release note entry in this section!

manuals/User/What_is.md

@@ -0,0 +1,8 @@
+{#User_What_is}
+# Descriptions for users
+
+```{toctree}
+:maxdepth: 1
+:hidden: true
+
+```

manuals/User/What_is/NGIpkgs.md

@@ -0,0 +1,21 @@
+{#User_What_is_NGIpkgs}
+# What is NGIpkgs?
+
+The [NGIpkgs repository](https://github.com/ngi-nix/ngipkgs)
+provides:
+- packages (`pkgs`) recipes
+in [Nix-the-language](https://nix.dev/tutorials/nix-language.html)
+to install software and all their dependencies using [a Nix-package-manager](#User_How_to_install_Nix)
+(mainly [`nix`](https://nix.dev/manual/nix));
+
+- `services` recipes
+in [Nix-the-language](https://nix.dev/tutorials/nix-language.html)
+to use those software inside a Nix configuration management framework
+(mainly [NixOS](https://nixos.org));
+
+- examples and tests of those services recipes.
+
+The Nix recipes maintained or being developed into NGIpkgs
+are for software funded by the [Next Generation Internet](https://www.ngi.eu) (NGI) initiative
+of the [European Commission](https://commission.europa.eu)
+through the [NLnet Foundation](https://nlnet.nl/).

manuals/User/What_is/Nix@NGI.md

@@ -0,0 +1,4 @@
+{#User_What_is_Nix_NGI}
+# What is Nix@NGI?
+
+ToDo

manuals/User/Why_to.md

@@ -0,0 +1,6 @@
+{#User_Why_to}
+# Explanations for users
+
+```{toctree}
+Why_to/install.md
+```

manuals/User/Why_to/install.md

@@ -0,0 +1,5 @@
+{#User_Why_to_install}
+# Why to install?
+
+```{toctree}
+```

manuals/User/Why_to/install/NGIpkgs.md

@@ -0,0 +1,17 @@
+{#User_Why_to_install_NGIpkgs}
+# Why to install NGIpkgs?
+
+This is what you can do with NGIpkgs:
+
+- Run locally programs provided by NGIpkgs,
+  on [any platform supporting an implementation of Nix](#User_How_to_install_Nix)
+  This does not require using the NixOS Linux distribution at all.
+
+- Develop you own software using libraries or tools
+  provided by NGIpkgs.
+
+- Deploy `systemd` (resp. `launchd`) services provided by NGIpkgs,
+  to hosts running [NixOS](https://nixos.org)
+  (resp. [nix-darwin](https://github.com/nix-darwin/nix-darwin)).
+
+For instructions, see [How to install NGIpkgs](#User_How_to_install_NGIpkgs).