Updated development section

Signed-off-by: Andreas Maier <maiera@de.ibm.com>
zhmcclient · Nov 9, 2020 · cc38911 · cc38911
1 parent eeefe06
commit cc38911
Showing 1 changed file with 68 additions and 76 deletions.
diff --git a/docs/source/development.rst b/docs/source/development.rst
@@ -1,4 +1,4 @@
-.. Copyright 2017 IBM Corp. All Rights Reserved.
+.. Copyright 2017-2020 IBM Corp. All Rights Reserved.
 ..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
@@ -18,18 +18,18 @@
 Development
 ===========
 
-This section only needs to be read by developers of the zhmc-ansible-modules
-project. People that want to make a fix or develop some extension, and people
-that want to test the project are also considered developers for the purpose of
-this section.
+This section only needs to be read by developers of the ibm.zhmc Ansible Galaxy
+collection project. People that want to make a fix or develop some extension,
+and people that want to test the project are also considered developers for
+the purpose of this section.
 
 
 .. _`Repository`:
 
 Repository
 ----------
 
-The repository for the zhmc-ansible-modules project is on GitHub:
+The repository for the ibm.zhmc Ansible Galaxy collection project is on GitHub:
 
 https://github.com/zhmcclient/zhmc-ansible-modules
 
@@ -48,13 +48,13 @@ Besides having a supported operating system with a supported Python version
 .. _virtual Python environment: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 
 Then, with a virtual Python environment active, clone the Git repo of this
-project and prepare the development environment with ``make setup``:
+project and prepare the development environment with ``make develop``:
 
 .. code-block:: text
 
     $ git clone git@github.com:zhmcclient/zhmc-ansible-modules.git
     $ cd zhmc-ansible-modules
-    $ make setup
+    $ make develop
 
 This will install all prerequisites the project needs for its development.
 
@@ -68,60 +68,56 @@ list of valid Make targets and a short description of what each target does.
 Building the documentation
 --------------------------
 
-The ReadTheDocs (RTD) site is used to publish the documentation for the
-zhmc-ansible-modules project at http://zhmc-ansible-modules.readthedocs.io/
+The documentation for the ibm.zhmc Ansible Galaxy collection is published
+on GitHub pages at https://zhmcclient.github.io/zhmc-ansible-modules/.
 
-This page automatically gets updated whenever the ``master`` branch of the
+That page automatically gets updated whenever the ``master`` branch of the
 Git repo for this package changes.
 
+**TBD: Verify the statement above.**
+
 In order to build the documentation locally from the Git work directory, issue:
 
 .. code-block:: text
 
     $ make docs
 
 The top-level document to open with a web browser will be
-``build/docs/html/index.html``.
+``docs/build/html/index.html``.
 
 
 .. _`Testing`:
 
 Testing
 -------
 
-To run unit tests in the currently active Python environment, issue one of
-these example variants of ``make test``:
+Again, an invocation of Make runs against the currently active Python environment.
 
-.. code-block:: text
+There are four kinds of tests currently, available as make targets:
 
-    $ make test                                  # Run all unit tests
-    $ TESTCASES=test_resource.py make test       # Run only this test source file
-    $ TESTCASES=TestInit make test               # Run only this test class
-    $ TESTCASES="TestInit or TestSet" make test  # py.test -k expressions are possible
+* ``make linkcheck`` - Check links in documentation
+* ``make test`` - Run unit and function tests with test coverage
+* ``make sanity`` - Run Ansible sanity tests (includes flake8, pylint, validate-modules)
+* ``make end2end`` - Run end2end tests (against a real environment)
 
-To run the unit tests and some more commands that verify the project is in good
-shape in all supported Python environments, use Tox:
+For the unit and function tests, the testcases and options for pytest
+can be specified via the nvironment variable ``TESTOPTS``, as shown in these
+examples:
 
 .. code-block:: text
 
-    $ tox                              # Run all tests on all supported Python versions
-    $ tox -e py27                      # Run all tests on Python 2.7
-    $ tox -e py27 test_resource.py     # Run only this test source file on Python 2.7
-    $ tox -e py27 TestInit             # Run only this test class on Python 2.7
-    $ tox -e py27 TestInit or TestSet  # py.test -k expressions are possible
-
-The positional arguments of the ``tox`` command are passed to ``py.test`` using
-its ``-k`` option. Invoke ``py.test --help`` for details on the expression
-syntax of its ``-k`` option.
+    $ make test                                      # Run all unit and function tests
+    $ TESTOPTS='-vv' make test                       # Specify -vv verbosity for pytest
+    $ TESTOPTS='-k test_partition.py' make test      # Run only this test source file
 
 
 .. _`Releasing a version`:
 
 Releasing a version
 -------------------
 
-This section shows the steps for releasing a version to `PyPI
-<https://pypi.python.org/>`_.
+This section shows the steps for releasing a version to `Ansible Galaxy
+<https://galaxy.ansible.com/>`_.
 
 It covers all variants of versions that can be released:
 
@@ -142,20 +138,20 @@ has the remote name ``origin`` in your local clone.
     * ``MN`` - Major and minor version numbers M.N of that full version
     * ``BRANCH`` - Name of the branch to be released
 
-    When releasing the master branch (e.g. as version ``0.6.0``):
+    When releasing the master branch (e.g. as version ``1.0.0``):
 
     .. code-block:: text
 
-        MNU=0.6.0
-        MN=0.6
+        MNU=1.0.0
+        MN=1.0
         BRANCH=master
 
-    When releasing a stable branch (e.g. as version ``0.5.1``):
+    When releasing a stable branch (e.g. as version ``0.8.1``):
 
     .. code-block:: text
 
-        MNU=0.5.1
-        MN=0.5
+        MNU=0.8.1
+        MN=0.8
         BRANCH=stable_$MN
 
 3.  Check out the branch to be released, make sure it is up to date with upstream, and
@@ -172,42 +168,41 @@ has the remote name ``origin`` in your local clone.
 
     .. code-block:: text
 
-        vi docs/changes.rst
+        vi docs/source/changes.rst
 
     and make the following changes in the section of the version to be released:
 
     * Finalize the version to the version to be released.
-    * Remove the statement that the version is in development.
-    * Change the release date to today´s date.
+    * Change the release date to today's date.
     * Make sure that all changes are described.
     * Make sure the items shown in the change log are relevant for and understandable
       by users.
-    * In the "Known issues" list item, remove the link to the issue tracker and add
-      text for any known issues you want users to know about.
-    * Remove all empty list items in that section.
+    * In the "Known issues" list item, remove the link to the issue tracker and
+      add text for any known issues you want users to know about.
+    * Remove all empty list items in the section of the version to be released.
 
 5.  Commit your changes and push them upstream:
 
     .. code-block:: text
 
-        git add docs/changes.rst
+        git add docs/source/changes.rst
         git commit -sm "Release $MNU"
         git push --set-upstream origin release_$MNU
 
 6.  On GitHub, create a Pull Request for branch ``release_$MNU``. This will trigger the
-    CI runs in Travis and Appveyor.
+    CI runs in Travis.
 
     Important: When creating Pull Requests, GitHub by default targets the ``master``
     branch. If you are releasing a stable branch, you need to change the target branch
     of the Pull Request to ``stable_M.N``.
 
 7.  On GitHub, close milestone ``M.N.U``.
 
-8.  Perform a complete test:
+8.  Perform a complete test in your preferred Python environment:
 
     .. code-block:: text
 
-        tox
+        make clobber all
 
     This should not fail because the same tests have already been run in the
     Travis CI. However, run it for additional safety before the release.
@@ -227,11 +222,13 @@ has the remote name ``origin`` in your local clone.
 
     * Merge the Pull Request (no review is needed).
 
-      Because this updates the ``stable_M.N`` branch, it triggers an RTD docs build of
+      Because this updates the ``stable_M.N`` branch, it triggers a docs build of
       its stable version. However, because the git tag for this version is not assigned
-      yet, this RTD build will show an incorrect version (a dev version based on the
+      yet, this docs build will show an incorrect version (a dev version based on the
       previous version tag). This will be fixed in a subsequent step.
 
+      **TBD: Verify the above on GitHub pages once established**
+
     * Delete the branch of the Pull Request (``release_M.N.U``)
 
 10. Checkout the branch you are releasing, update it from upstream, and delete the local
@@ -253,9 +250,11 @@ has the remote name ``origin`` in your local clone.
         git tag $MNU
         git push --tags
 
-    The pushing of the tag triggers another RTD docs build of its stable version, this time
+    The pushing of the tag triggers another docs build of its stable version, this time
     with the correct version as defined in the tag.
 
+    **TBD: Verify the above on GitHub pages once established**
+
     If the previous commands fail because this tag already exists for some reason, delete
     the tag locally and remotely:
 
@@ -266,23 +265,18 @@ has the remote name ``origin`` in your local clone.
 
     and try again.
 
-12. On RTD, verify that it shows the correct version for its stable version:
+12. On GitHub pages, verify that it shows the correct version for its stable version:
 
-    RTD stable version: https://zhmc-ansible-modules.readthedocs.io/en/stable.
+    https://github.io/zhmc-ansible-modules
 
-    If it does not, trigger a build of RTD version "stable" on the RTD project
-    page:
-
-    RTD build page: https://readthedocs.org/projects/zhmc-ansible-modules/builds/
-
-    Once that build is complete, verify again.
+    **TBD: Verify the above on GitHub pages once established**
 
 13. On GitHub, edit the new tag ``M.N.U``, and create a release description on it. This
     will cause it to appear in the Release tab.
 
     You can see the tags in GitHub via Code -> Releases -> Tags.
 
-14. Upload the package to PyPI:
+14. Publish the collection to Ansible Galaxy:
 
     .. code-block:: text
 
@@ -294,10 +288,11 @@ has the remote name ``origin`` in your local clone.
     without any development suffix) is shown.
 
     **Attention!!** This only works once for each version. You cannot
-    re-release the same version to PyPI, or otherwise update it.
+    re-release the same version to Ansible Galaxy, or otherwise update it.
+
+    Verify that the released version arrived on Ansible Galaxy:
 
-    Verify that the released version arrived on PyPI:
-    https://pypi.python.org/pypi/zhmc-ansible-modules/
+    **TBD: Add link to ibm.zhmc collection on Ansible Galaxy**
 
 15. If you released the master branch, it needs a new fix stream.
 
@@ -309,11 +304,6 @@ has the remote name ``origin`` in your local clone.
         git checkout -b stable_$MN
         git push --set-upstream origin stable_$MN
 
-    Log on to the
-    `RTD project zhmc-ansible-modules <https://readthedocs.org/projects/zhmc-ansible-modules/versions>`_
-    and activate the new version (=branch) ``stable_M.N`` as a version to be
-    built.
-
 
 .. _`Starting a new version`:
 
@@ -343,20 +333,20 @@ has the remote name ``origin`` in your local clone.
     * ``MN`` - Major and minor version numbers M.N of that full version
     * ``BRANCH`` - Name of the branch the new version is based upon
 
-    When starting a (major or minor) version (e.g. ``0.6.0``) based on the master branch:
+    When starting a (major or minor) version (e.g. ``1.1.0``) based on the master branch:
 
     .. code-block:: text
 
-        MNU=0.6.0
-        MN=0.6
+        MNU=1.1.0
+        MN=1.0
         BRANCH=master
 
-    When starting an update (=fix) version (e.g. ``0.5.1``) based on a stable branch:
+    When starting an update (=fix) version (e.g. ``0.8.2``) based on a stable branch:
 
     .. code-block:: text
 
-        MNU=0.5.1
-        MN=0.5
+        MNU=0.8.2
+        MN=0.8
         BRANCH=stable_$MN
 
 3.  Check out the branch the new version is based on, make sure it is up to
@@ -373,13 +363,13 @@ has the remote name ``origin`` in your local clone.
 
     .. code-block:: text
 
-        vi docs/changes.rst
+        vi docs/source/changes.rst
 
     and insert the following section before the top-most section:
 
     .. code-block:: text
 
-        Version 0.6.0
+        Version 1.1.0
         ^^^^^^^^^^^^^
 
         Released: not yet
@@ -392,6 +382,8 @@ has the remote name ``origin`` in your local clone.
 
         **Enhancements:**
 
+        **Cleanup:**
+
         **Known issues:**
 
         * See `list of open issues`_.