Add automatic release on PyPI (#729)

- triggered on publishing a GH release
- includes creation of release documentation
- add PR templates, adapt issue templates
- minor documentation changes

Author: mrbean-bremen

.github/ISSUE_TEMPLATE/bug_report.md

@@ -8,17 +8,19 @@ assignees: ''
 ---
 
 **Describe the bug**
-A clear and concise description of what the bug is.
-Please provide a stack trace if available.
+Describe the observed behavior, and what you expect to happen instead.
+In case of a crash, please provide the complete stack trace.
 
 **How To Reproduce**
-Please provide a unit test or a minimal code snippet that reproduces the 
-problem.
+Please provide a unit test or a minimal reproducible example that shows 
+the problem.
 
 **Your environment**
-Please run the following and paste the output.
+Please run the following in the environment where the problem happened and 
+paste the output.
 ```bash
 python -c "import platform; print(platform.platform())"
 python -c "import sys; print('Python', sys.version)"
 python -c "from pyfakefs.fake_filesystem import __version__; print('pyfakefs', __version__)"
+python -c "import pytest; print('pytest', pytest.__version__)"
 ```

.github/ISSUE_TEMPLATE/feature_request.md

@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: ''
-labels: ''
+labels: 'enhancement'
 assignees: ''
 
 ---

.github/PULL_REQUEST_TEMPLATE/code_pr.md

@@ -0,0 +1,18 @@
+---
+name: Bug fix or feature implementation
+about: Create a pull request for changed code
+---
+
+<!--
+Please prefix your PR title with [WIP] for PRs that are still in progress.
+-->
+
+#### Describe the changes
+The related issue or a description of the bug or feature that this PR addresses.
+
+#### Tasks
+- [ ] Unit tests added that reproduce the issue or prove feature is working
+- [ ] Fix or feature added
+- [ ] Entry to release notes added
+- [ ] Linter and mypy show no errors
+- [ ] Unit tests passing

.github/PULL_REQUEST_TEMPLATE/documentation_pr.md

@@ -0,0 +1,8 @@
+---
+name: Documentation change
+about: Create a pull request for improved or fixed documentation
+---
+
+#### Describe the changes
+A short description of the fixed or improved documentation, and the related 
+issue if applicable.

.github/workflows/release-deploy.yml

@@ -0,0 +1,65 @@
+name: release-deploy
+
+on:
+  release:
+    types: [ published ]
+
+jobs:
+
+  deploy:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: [ '3.10' ]
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        path: main
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Build package
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install build
+        cd main
+        echo "RELEASE_VERSION=$(cat pyfakefs/_version.py | cut -d "'" -f 2)" >> $GITHUB_ENV
+        python -m build
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@master
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_TOKEN }}
+
+    - name: Create release docs
+      run: |
+        python -m pip install wheel
+        python -m pip install pytest
+        python -m pip install sphinx
+        cd main/docs
+        make html
+
+    - name: Checkout gh-pages
+      uses: actions/checkout@v2
+      with:
+        ref: gh-pages
+        path: doc
+
+    - name: Copy and commit release documentation
+      run: |
+        cp -r main/gh-pages/* doc/release
+        cd doc
+        sed "s/href=\"release\/index.html\">Pyfakefs .*/href=\"release\/index.html\">Pyfakefs $RELEASE_VERSION/" index.html > index1.html
+        rm index.html
+        mv index1.html index.html
+        git config user.name "CI Build"
+        git config user.email "[email protected]"
+        git add release/*
+        git commit -a -m "Release $RELEASE_VERSION documentation"
+        git push

CHANGES.md

@@ -1,17 +1,18 @@
 # pyfakefs Release Notes
-The released versions correspond to PyPi releases.
+The released versions correspond to PyPI releases.
 
 ## Version 5.0.0 - unreleased
 New version after the transfer to `pytest-dev`.
 
 ### Changes
-* the long deprecated old-style API is now removed
-* the deprecated method `copyRealFile` has been removed - use 
-  `add_real_file` instead
+* the old-style API deprecated since version 3.4 has now been removed
+* the method `copyRealFile` deprecated since version 3.2 has been removed - 
+  use `add_real_file` instead
 
 ### Infrastructure
 * transferred the repository to the `pytest-dev` organization
 * renamed the `master` branch to `main`
+* added automatic PyPI release workflow 
 
 ### New Features
 * added some support for `st_blocks` in stat result
@@ -195,7 +196,7 @@ This is a bugfix release.
 ## [Version 4.5.0](https://pypi.python.org/pypi/pyfakefs/4.5.0) (2021-06-04)
 Adds some support for Python 3.10 and basic type checking.
 
-_Note_: This version has been yanked from PyPi as it erroneously allowed
+_Note_: This version has been yanked from PyPI as it erroneously allowed
 installation under Python 3.5.
 
 ### New Features
@@ -364,7 +365,7 @@ This is a bugfix release that fixes a regression issue.
 ## [Version 4.0.2](https://pypi.python.org/pypi/pyfakefs/4.0.2) (2020-03-04)
 
 This as a patch release that only builds for Python 3. Note that 
-versions 4.0.0 and 4.0.1 will be removed from PyPi to disable
+versions 4.0.0 and 4.0.1 will be removed from PyPI to disable
 installing them under Python 2. 
 
 #### Fixes
@@ -374,7 +375,7 @@ installing them under Python 2.
 
 This as a bug fix release for a regression bug.
 
-_Note_: This version has been yanked from PyPi as it erroneously allowed
+_Note_: This version has been yanked from PyPI as it erroneously allowed
 installation under Python 2. This has been fixed in version 4.0.2.
 
 #### Fixes
@@ -384,7 +385,7 @@ installation under Python 2. This has been fixed in version 4.0.2.
 pyfakefs 4.0.0 drops support for Python 2.7. If you still need
 Python 2.7, you can continue to use pyfakefs 3.7.x.
 
-_Note_: This version has been yanked from PyPi as it erroneously allowed
+_Note_: This version has been yanked from PyPI as it erroneously allowed
 installation under Python 2. This has been fixed in version 4.0.2.
 
 #### Changes
@@ -799,7 +800,7 @@ This is the last release that supports Python 2.6.
     File contents are read from the real file system only as needed ([#170](../../issues/170)).
     See `example_test.py` for a usage example.
   * Deprecated `TestCase.copyRealFile()` in favor of `add_real_file()`.
-    `copyRealFile()` remains only for backward compatability.  Also, some
+    `copyRealFile()` remains only for backward compatibility.  Also, some
     less-popular argument combinations have been disallowed.
   * Added this file you are reading, `CHANGES.md`, to the release manifest
 
@@ -908,5 +909,5 @@ This is the last release that supports Python 2.6.
  * Relative paths not supported ([#16](../../issues/16), [#17](../../issues/17)))
 
 ## Older Versions
-There are no release notes for releases 2.6 and below.  The following versions are still available on PyPi:
+There are no release notes for releases 2.6 and below.  The following versions are still available on PyPI:
  * [1.1](https://pypi.python.org/pypi/pyfakefs/1.1), [1.2](https://pypi.python.org/pypi/pyfakefs/1.2), [2.0](https://pypi.python.org/pypi/pyfakefs/2.0), [2.1](https://pypi.python.org/pypi/pyfakefs/2.1), [2.2](https://pypi.python.org/pypi/pyfakefs/2.2), [2.3](https://pypi.python.org/pypi/pyfakefs/2.3) and [2.4](https://pypi.python.org/pypi/pyfakefs/2.4)

README.md

@@ -5,22 +5,22 @@ Using pyfakefs, your tests operate on a fake file system in memory without
 touching the real disk. The software under test requires no modification to
 work with pyfakefs.
 
-pyfakefs provides the `fs` fixture for use with `pytest`, which will 
+pyfakefs acts as a `pytest` plugin by providing the `fs` fixture, which will 
 automatically invoke the fake filesystem. It also provides 
 the `fake_filesystem_unittest.TestCase` class for use with `unittest` and 
 the means to use the fake filesystem with other test frameworks. 
 
-pyfakefs works with Linux, Windows and macOS.
+pyfakefs works with current versions of Linux, Windows and macOS.
 
 ## Documentation
 
-This file provides general usage instructions for pyfakefs.  There is more:
+This document provides a general overview for pyfakefs.  There is more:
 
 * The documentation at [GitHub Pages:](http://pytest-dev.github.io/pyfakefs)
   * The [Release documentation](http://pytest-dev.github.io/pyfakefs/release)
     contains usage documentation for pyfakefs and a description of the 
     most relevant classes, methods and functions for the last version 
-    released on PyPi
+    released on PyPI
   * The [Development documentation](http://pytest-dev.github.io/pyfakefs/main)
     contains the same documentation for the current main branch
   * The [Release 3.7 documentation](http://pytest-dev.github.io/pyfakefs/release37)
@@ -36,6 +36,16 @@ Refer to the
 for information on other test scenarios, test customization and 
 using convenience functions.
 
+## Features
+Apart from automatically mocking most file-system functions, pyfakefs 
+provides some additional features:
+- mapping files and directories from the real file system into the fake filesystem
+- configuration and tracking of the file system size
+- pause and resume of patching to be able to use the real file system inside a 
+  test step
+- (limited) emulation of other OSes (Linux, macOS or Windows)
+- configuration to behave as if running as a non-root user while running 
+  under root
 
 ## Compatibility
 pyfakefs works with CPython 3.7 and above, on Linux, Windows and macOS, and 
@@ -46,10 +56,10 @@ though a current version is recommended.
 
 pyfakefs will not work with Python libraries that use C libraries to access the
 file system. This is because pyfakefs cannot patch the underlying C libraries'
-file access functions--the C libraries will always access the real file system.
-For example, pyfakefs will not work with [`lxml`](http://lxml.de/).  In this case
-`lxml` must be replaced with a pure Python alternative such as
-[`xml.etree.ElementTree`](https://docs.python.org/3/library/xml.etree.elementtree.html).
+file access functions--the C libraries will always access the real file 
+system. Refer to the 
+[documentation](https://pytest-dev.github.io/pyfakefs/release/intro.html#limitations)
+for more information about the limitations of pyfakefs.
 
 ## Development
 

docs/intro.rst

@@ -14,8 +14,8 @@ providing the `fs` fixture that enables the fake filesystem.
 
 Installation
 ------------
-pyfakefs is available on `PyPi <https://pypi.python.org/pypi/pyfakefs/>`__.
-The latest released version can be installed from pypi:
+pyfakefs is available on `PyPI <https://pypi.python.org/pypi/pyfakefs/>`__.
+The latest released version can be installed from PyPI:
 
 .. code:: bash
 

docs/usage.rst

@@ -714,7 +714,7 @@ the ``fs`` fixture.
 
 Handling mount points
 ~~~~~~~~~~~~~~~~~~~~~
-Under Linux and MacOS, the root path (``/``) is the only mount point created
+Under Linux and macOS, the root path (``/``) is the only mount point created
 in the fake file system. If you need support for more mount points, you can add
 them using ``add_mount_point()``.
 
@@ -806,7 +806,7 @@ Here is the same code using a context manager:
 
 Simulating other file systems
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``Pyfakefs`` supports Linux, MacOS and Windows operating systems. By default,
+``Pyfakefs`` supports Linux, macOS and Windows operating systems. By default,
 the file system of the OS where the tests run is assumed, but it is possible
 to simulate other file systems to some extent. To set a specific file
 system, you can change ``pyfakefs.FakeFilesystem.os`` to one of
@@ -820,11 +820,11 @@ attributes, which can also be set separately if needed:
 
   - ``is_windows_fs`` -  if ``True`` a Windows file system (NTFS) is assumed
   - ``is_macos`` - if ``True`` and ``is_windows_fs`` is ``False``, the
-    standard MacOS file system (HFS+) is assumed
+    standard macOS file system (HFS+) is assumed
   - if ``is_windows_fs`` and ``is_macos`` are ``False``, a Linux file system
     (something like ext3) is assumed
   - ``is_case_sensitive`` is set to ``True`` under Linux and to ``False``
-    under Windows and MacOS by default - you can change it to change the
+    under Windows and macOS by default - you can change it to change the
     respective behavior
   - ``path_separator`` is set to ``\`` under Windows and to ``/`` under Posix,
     ``alternative_path_separator`` is set to ``/`` under Windows and to