From a09d3d69f991220ff710b46370403959663a6e8f Mon Sep 17 00:00:00 2001
From: Marti Bolivar <marti.bolivar@nordicsemi.no>
Date: Wed, 28 Aug 2019 00:42:01 -0600
Subject: [PATCH] doc: west: add tl;dr for moving to west and troubleshooting

These are based on user feedback on slack and the mailing list.

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
---
 doc/guides/west/index.rst           |  2 +
 doc/guides/west/moving-to-west.rst  | 57 +++++++++++++++++++++++++++++
 doc/guides/west/troubleshooting.rst | 51 ++++++++++++++++++++++++++
 3 files changed, 110 insertions(+)
 create mode 100644 doc/guides/west/moving-to-west.rst
 create mode 100644 doc/guides/west/troubleshooting.rst

diff --git a/doc/guides/west/index.rst b/doc/guides/west/index.rst
index 4f27fd14d4c..e7828e22ac1 100644
--- a/doc/guides/west/index.rst
+++ b/doc/guides/west/index.rst
@@ -34,6 +34,8 @@ context about the tool.
    :maxdepth: 1
 
    install.rst
+   moving-to-west.rst
+   troubleshooting.rst
    repo-tool.rst
    manifest.rst
    config.rst
diff --git a/doc/guides/west/moving-to-west.rst b/doc/guides/west/moving-to-west.rst
new file mode 100644
index 00000000000..51e8d44936e
--- /dev/null
+++ b/doc/guides/west/moving-to-west.rst
@@ -0,0 +1,57 @@
+.. _moving-to-west:
+
+Moving to West
+##############
+
+To convert a "pre-west" Zephyr setup on your computer to west, follow these
+steps. If you are starting from scratch, use the :ref:`getting_started`
+instead. See :ref:`west-troubleshooting` for advice on common issues.
+
+#. Install west.
+
+   On Linux::
+
+     pip3 install --user -U west
+
+   On Windows and macOS::
+
+     pip3 install -U west
+
+   For details, see :ref:`west-install`.
+
+#. Move your zephyr repository to a new :file:`zephyrproject` parent directory,
+   and change directory there.
+
+   On Linux and macOS::
+
+     mkdir zephyrproject
+     mv zephyr zephyrproject
+     cd zephyrproject
+
+   On Windows ``cmd.exe``::
+
+     mkdir zephyrproject
+     move zephyr zephyrproject
+     chdir zephyrproject
+
+   The name :file:`zephyrproject` is recommended, but you can choose any name
+   with no spaces anywhere in the path.
+
+#. Create a :ref:`west installation <west-installation>` using the zephyr
+   repository as a local manifest repository::
+
+     west init -l zephyr
+
+   This creates :file:`zephyrproject/.west`, marking the root of your
+   installation, and does some other setup. It will not change the contents of
+   the zephyr repository in any way.
+
+#. Clone the rest of the repositories used by zephyr::
+
+     west update
+
+   **Make sure to run this command whenever you pull zephyr.** Otherwise, your
+   local repositories will get out of sync. (Run ``west list`` for current
+   information on these repositories.)
+
+You are done: :file:`zephyrproject` is now set up to use west.
diff --git a/doc/guides/west/troubleshooting.rst b/doc/guides/west/troubleshooting.rst
new file mode 100644
index 00000000000..1f1fdc21811
--- /dev/null
+++ b/doc/guides/west/troubleshooting.rst
@@ -0,0 +1,51 @@
+.. _west-troubleshooting:
+
+Troubleshooting West
+####################
+
+This page covers common issues with west and how to solve them.
+
+"invalid choice: 'post-init'"
+*****************************
+
+If you see this error when running ``west init``:
+
+.. code-block:: none
+
+   west: error: argument <command>: invalid choice: 'post-init'
+   (choose from 'init', 'update', 'list', 'manifest', 'diff',
+   'status', 'forall', 'config', 'selfupdate', 'help')
+
+Then you have an old version of west installed, and are trying to use it in an
+installation that requires a more recent version.
+
+The easiest way to resolve this issue is to upgrade west and retry as follows:
+
+#. Install the latest west with the ``-U`` option for ``pip3 install`` as shown
+   in :ref:`west-install`.
+
+#. Back up any contents of :file:`zephyrproject/.west/config` that you want to
+   save. (If you don't have any configuration options set, it's safe to skip
+   this step.)
+
+#. Completely remove the :file:`zephyrproject/.west` directory (if you don't,
+   you will get the "already in an installation" error message discussed next).
+
+#. Run ``west init`` again.
+
+"already in an installation"
+****************************
+
+You may see this error when running ``west init``:
+
+.. code-block:: none
+
+   FATAL ERROR: already in an installation (<some directory>), aborting
+
+If this is unexpected and you're really trying to create a new installation,
+then it's likely that west is using the :envvar:`ZEPHYR_BASE` :ref:`environment
+variable <env_vars>` to locate a west installation elsewhere on your system.
+This is intentional behavior; it allows you to put your Zephyr applications in
+any directory and still use west.
+
+To resolve this issue, unset :envvar:`ZEPHYR_BASE` and try again.