From dbd1c75341d25e3bee72051e3dc9a297e4ed9782 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rados=C5=82aw=20Wa=C5=9Bko?= <radoslaw.wasko@enso.org>
Date: Sat, 3 Jul 2021 17:00:01 +0200
Subject: [PATCH] Document how to share libraries manually

---
 docs/libraries/README.md  |  1 +
 docs/libraries/sharing.md | 67 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 docs/libraries/sharing.md

diff --git a/docs/libraries/README.md b/docs/libraries/README.md
index 496d71b78946..279cdb95235b 100644
--- a/docs/libraries/README.md
+++ b/docs/libraries/README.md
@@ -14,3 +14,4 @@ Documents in this section describe Enso's library ecosystem.
   organizes library versioning.
 - [**Repositories:**](./repositories.md) Information on the structure of
   repositories providing Enso libraries and Editions.
+- [**Sharing Libraries:**](./sharing.md) Information on how to share libraries.
diff --git a/docs/libraries/sharing.md b/docs/libraries/sharing.md
new file mode 100644
index 000000000000..39ebd17ae7cc
--- /dev/null
+++ b/docs/libraries/sharing.md
@@ -0,0 +1,67 @@
+---
+layout: developer-doc
+title: Sharing Libraries
+category: libraries
+tags: [libraries, editions, sharing]
+order: 3
+---
+
+# Sharing Libraries
+
+This document explains how users can share Enso libraries.
+
+<!-- MarkdownTOC levels="2,3" autolink="true" -->
+
+<!-- /MarkdownTOC -->
+
+## Sharing Privately
+
+To prepare the project for sharing make sure that it has a proper `namespace`
+field set in `package.yaml`. It should be set to something unique, like your
+username.
+
+> The field `namespace` is a temporary workaround and in the near future it will
+> be deprecated and handled mostly automatically. For now however you need to
+> set it properly.
+
+To share an Enso library all you need to do is to package the project into an
+archive (for example ZIP) and share it (through e-mail, cloud drive services
+etc.) with your peers. Now to be able to use the library that was shared with
+you, you need to extract it to the directory
+`~/enso/libraries/<namespace>/<Project_Name>` (where on Windows `~` should be
+interpreted as your user home directory). To make sure that the library is
+extracted correctly, make sure that under the path
+`~/enso/libraries/<namespace>/<Project_Name>/package.yaml` and that its
+`namespace` field has the same value as the name of the `<namespace>` directory.
+
+> The below step is not necessary yet, but it will be needed once the editions
+> system is fully integrated, so it is better to perform it for forwards
+> compatibility.
+
+Now you need to set-up your project properly to be able to use this unpublished
+library. The simplest way to do that is to set `prefer-local-libraries` in your
+project's `package.yaml` to `true`. This will make all libraries from
+`~/enso/libraries` take precedence over published libraries set-up in the
+edition. Alternatively, if you do not want to override all libraries, but only
+some of them, you can add a local library override, by adding a proper entry in
+the `libraries` section of the `edition` in your project's `package.yaml`, like
+shown below:
+
+```yaml
+edition:
+   (...)
+   libraries:
+     - name: <namespace>.<Project_Name>
+       repository: local
+```
+
+Now, you can use your library by adding a proper import to your project:
+
+```
+import <namespace>.<Project_Name>
+```
+
+## Publishing
+
+> Soon it will be possible to share the libraries through the Marketplace, but
+> it is still a work in progress.