1 files changed, 71 insertions, 0 deletions

diff --git a/docs/namespaces.md b/docs/namespaces.md
new file mode 100644
index 00000000..f00c692a
--- /dev/null
+++ b/docs/namespaces.md
@@ -0,0 +1,71 @@
+# Namespaces
+
+The LuaRocks.org repository allows for each user to published their own
+collection of rocks. Since LuaRocks 3, this concept of per-user rocks has been
+integrated into the tool, in the form of **namespaces**.
+
+What you can do with namespaces:
+
+* Install packages using a namespace:
+  * `luarocks install my_user/my_rock`
+* Depend on a specific namespaced version of a rock in your rockspec:
+  * `dependencies = { "my_user/my_rock > 2.0" }`
+
+## Background
+
+LuaRocks has always supported multiple repositories, which can be set in the
+[config file](config_file_format.md) with the `rocks_servers` entry. A
+repository is an address (a local directory or a remote URL) where LuaRocks
+can find a `manifest-5.x` file and .rock and .rockspec files. We also call
+such repository a "manifest", for short. 
+
+The [LuaRocks.org](LuaRocks.org)(LuaRocks.org)(https://luarocks.org) website
+features a root manifest at `https://luarocks.org` as well as per-user
+manifests at `https://luarocks.org/manifests/<your-user-name>`. Entries in the
+root manifest are operated in a first-come first-served manner, but even if
+someone else has already taken a rock name, you can upload your own version of
+it to your user manifest. You can refer to a per-user manifest the same way as
+any other rocks server, adding to your configuration or using it with the
+`--server` flag. This means that you were always able to install your own
+version of a rock using a command such as `luarocks install <my-rock>
+--server=https://luarocks.org/manifests/<your-user-name>`. However, you could
+not specifically depend on it from another rockspec, and once installed, the
+information that this rock came from a specific manifest was lost. With
+namespaces, now you can!
+
+## Using namespaces
+
+All `luarocks` commands that accept a rock name as command line argument can
+now take a namespaced variant:
+
+```
+luarocks install my_user/my_rock
+```
+
+LuaRocks will take your `rocks_trees` configuration and search for namespaced
+manifests on each entry: for example, given the default server
+`https://luarocks.org` it will look in
+`https://luarocks.org/manifests/my_user`.
+
+When installing, LuaRocks will internally store the information that this copy
+of `my_rock` came from the `my_user` namespace, so it will be able to use that
+information when another rockspec specifically asks for `my_user/my_rock` in
+its dependencies. (The namespace information is stored in a separate
+`rock_namespace` metadata file, at
+`lib/luarocks/rocks-5.x/my_rock/1.0-1/rock_namespace`, relative to your local
+rocks tree.)
+
+## Compatibility between non-namespaced and namespaced rocks
+
+A namespaced package can stand for a non-namespaced one. If you have
+`my_user/my_rock 1.0` installed and a rock depends on `my_rock 1.0`, the
+installed rock will satisfy the dependency.
+
+The opposite is not true: if you have `my_rock 1.0` installed but that did not
+come from a `my_user` namespace, it will not satisfy a dependency for
+`my_user/my_rock`.
+
+## Current limitations
+
+You cannot have two rocks with the same name and version but different
+namespaces installed at the same time in the same local rocks tree.