Add a FAQ

2 files changed, 34 insertions, 0 deletions

diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 0000000..fe71198
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,33 @@
+###
+FAQ
+###
+
+I cannot edit the merge request / issue I've just retrieved
+    It is likely that you used a ``MergeRequest``, ``GroupMergeRequest``,
+    ``Issue`` or ``GroupIssue`` object. These objects cannot be edited. But you
+    can create a new ``ProjectMergeRequest`` or ``ProjectIssue`` object to
+    apply changes. For example::
+
+        issue = gl.issues.list()[0]
+        project = gl.projects.get(issue.project_id, lazy=True)
+        editable_issue = project.issues.get(issue.iid, lazy=True)
+        # you can now edit the object
+
+    See the :ref:`merge requests example <merge_requests_examples>` and the
+    :ref:`issues examples <issues_examples>`.
+
+How can I clone the repository of a project?
+    python-gitlab doesn't provide an API to clone a project. You have to use a
+    git library or call the ``git`` command.
+
+    The git URI is exposed in the ``ssh_url_to_repo`` attribute of ``Project``
+    objects.
+
+    Example::
+
+        import subprocess
+
+        project = gl.projects.create(data)  # or gl.projects.get(project_id)
+        print(project.attributes)  # displays all the attributes
+        git_url = project.ssh_url_to_repo
+        subprocess.call(['git', 'clone', git_url])
diff --git a/docs/index.rst b/docs/index.rst
index 7805fcf..9c8cfd3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Contents:
    install
    cli
    api-usage
+   faq
    switching-to-v4
    api-objects
    api/gitlab