document the API migration from 0.10

docs/index.rst

@@ -14,6 +14,7 @@ Contents:
    install
    cli
    api-usage
+   upgrade-from-0.10
    api/gitlab
 
 

docs/upgrade-from-0.10.rst

@@ -0,0 +1,125 @@
+#############################################
+Upgrading from python-gitlab 0.10 and earlier
+#############################################
+
+``python-gitlab`` 0.11 introduces new objects which make the API cleaner and
+easier to use. The feature set is unchanged but some methods have been
+deprecated in favor of the new manager objects.
+
+Deprecated methods will be remove in a future release.
+
+Gitlab object migration
+=======================
+
+The objects constructor methods are deprecated:
+
+* ``Hook()``
+* ``Project()``
+* ``UserProject()``
+* ``Group()``
+* ``Issue()``
+* ``User()``
+* ``Team()``
+
+Use the new managers objects instead. For example:
+
+.. code-block:: python
+
+   # Deprecated syntax
+   p1 = gl.Project({'name': 'myCoolProject'})
+   p1.save()
+   p2 = gl.Project(id=1)
+   p_list = gl.Project()
+
+   # New syntax
+   p1 = gl.projects.create({'name': 'myCoolProject'})
+   p2 = gl.projects.get(1)
+   p_list = gl.projects.list()
+
+The following methods are also deprecated:
+
+* ``search_projects()``
+* ``owned_projects()``
+* ``all_projects()``
+
+Use the ``projects`` manager instead:
+
+.. code-block:: python
+
+   # Deprecated syntax
+   l1 = gl.search_projects('whatever')
+   l2 = gl.owned_projects()
+   l3 = gl.all_projects()
+
+   # New syntax
+   l1 = gl.projects.search('whatever')
+   l2 = gl.projects.owned()
+   l3 = gl.projects.all()
+
+GitlabObject objects migration
+==============================
+
+The following constructor methods are deprecated in favor of the matching
+managers:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Deprecated method
+     - Matching manager
+   * - ``User.Key()``
+     - ``User.keys``
+   * - ``CurrentUser.Key()``
+     - ``CurrentUser.keys``
+   * - ``Group.Member()``
+     - ``Group.members``
+   * - ``ProjectIssue.Note()``
+     - ``ProjectIssue.notes``
+   * - ``ProjectMergeRequest.Note()``
+     - ``ProjectMergeRequest.notes``
+   * - ``ProjectSnippet.Note()``
+     - ``ProjectSnippet.notes``
+   * - ``Project.Branch()``
+     - ``Project.branches``
+   * - ``Project.Commit()``
+     - ``Project.commits``
+   * - ``Project.Event()``
+     - ``Project.events``
+   * - ``Project.File()``
+     - ``Project.files``
+   * - ``Project.Hook()``
+     - ``Project.hooks``
+   * - ``Project.Key()``
+     - ``Project.keys``
+   * - ``Project.Issue()``
+     - ``Project.issues``
+   * - ``Project.Label()``
+     - ``Project.labels``
+   * - ``Project.Member()``
+     - ``Project.members``
+   * - ``Project.MergeRequest()``
+     - ``Project.mergerequests``
+   * - ``Project.Milestone()``
+     - ``Project.milestones``
+   * - ``Project.Note()``
+     - ``Project.notes``
+   * - ``Project.Snippet()``
+     - ``Project.snippets``
+   * - ``Project.Tag()``
+     - ``Project.tags``
+   * - ``Team.Member()``
+     - ``Team.members``
+   * - ``Team.Project()``
+     - ``Team.projects``
+
+For example:
+
+.. code-block:: python
+
+   # Deprecated syntax
+   p = gl.Project(id=2)
+   issues = p.Issue()
+
+   # New syntax
+   p = gl.projects.get(2)
+   issues = p.issues.list()