From ce487905cda7bb4512583c75cab3d7c7b53863de Mon Sep 17 00:00:00 2001
From: Zach Mitchell <zmitchell@fastmail.com>
Date: Tue, 27 Jun 2023 22:16:02 -0600
Subject: [PATCH] Add outline for sharing deps tutorial

---
 .../tutorial-outlines/sharing-dependencies.md | 64 +++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 maintainers/working_groups/learning_journey/tutorial-outlines/sharing-dependencies.md

diff --git a/maintainers/working_groups/learning_journey/tutorial-outlines/sharing-dependencies.md b/maintainers/working_groups/learning_journey/tutorial-outlines/sharing-dependencies.md
new file mode 100644
index 0000000..fc2de6a
--- /dev/null
+++ b/maintainers/working_groups/learning_journey/tutorial-outlines/sharing-dependencies.md
@@ -0,0 +1,64 @@
+# Sharing dependencies between `default.nix` and `shell.nix`
+
+## Assumptions
+- The reader has seen a derivation before.
+- The reader understands that builders come from `nixpkgs`.
+- The reader knows what a shell environment is.
+
+## Activity
+
+<!-- What is the activity you're going to walk the reader through. -->
+- Start with a `default.nix` that builds a project.
+- Show the reader how to share dependencies between a build and a shell environment.
+
+## Purpose
+
+<!-- What is the reader supposed to gain from reading this? --> 
+- Show the reader how to set up a development environment.
+- Show the reader how not to repeat themselves.
+- Show the reader how to import one Nix file into another.
+
+## Steps
+
+<!-- Prepare a bulleted outline of how you're going to walk the reader through this activity. -->
+<!-- Be specific about how you're going to teach this activity, we want to catch any pitfalls before the writing phase. -->
+- Begin with a `default.nix` that builds an application.
+- Show the reader that the application builds.
+- Present a scenario that prompts for a better working environment.
+    - We'd like to include modern development tooling like a test runner, linter, and formatter.
+    - Demonstrate that in order to bring those tools into our environment with the current `default.nix` those packages would also be included in the build even though they aren't necessary to build our application. 
+        - (Optional) Add the packages to `propagatedBuildInputs` and show that they're included in the closure.
+- Create a `shell.nix` to separate build dependencies from development dependencies.
+    - Duplicate dependencies from `default.nix` so that you can still perform the build in `shell.nix`.
+    - Add the development tools to `shell.nix` so that the reader has access to the during development.
+    - Demonstrate that you can still build the application.
+    - Explain that having to repeat yourself in both files is less than ideal and that you could easily forget to add a dependency to one file or the other.
+- Introduce `mkShell.inputsFrom` as a way to prevent duplication.
+    - Explain that `inputsFrom` extracts `input` attributes from the supplied derivation and passes them to `mkShell`.
+- Demonstrate how to import the `default.nix` and use its inputs.
+- Demonstrate how to put the `mkShell` call in `default.nix`.
+    - Explain that defining the shell this way helps to keep more of the functionality in `default.nix`, leaving `shell.nix` to be the necessary glue to allow `nix-shell` to use the shell we've defined.
+
+In the end you should end up with files that look like this (examples are Python just for demonstration purposes here):
+```
+# default.nix
+let
+  myPackage = python3Packages.buildPythonApplication {
+    propagatedBuildInputs = [
+      python3Packages.flask
+    ];
+  };
+in myPackage // {
+  shell = mkShell {
+    inputsFrom = [
+      myPackage
+    ];
+    buildInputs = [
+      curl
+    ];
+  };
+}
+
+# shell.nix
+(import ./default.nix).shell
+```