Merge pull request #30 from GPflow/develop

Release 0.2.0.

.github/workflows/benchmark.yml

@@ -0,0 +1,56 @@
+name: benchmark
+
+on:
+  schedule:
+    # * is a special character in YAML so you have to quote this string
+    # 10:17 every Monday - A compromise between random and a convenient time:
+    - cron: '17 10 * * 1'
+
+env:
+  penv: './poetryenv poetryenvs'
+  run: 'run python benchmark'
+  bex: 'benchmark/examples'
+  res: 'gh-pages/benchmark_results'
+  plots: 'gh-pages/docs/benchmark_plots/'
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+          path: gh-pages
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Install
+        run: |
+          curl -sSL https://install.python-poetry.org | python3 -
+          pip install -r poetryenv_requirements.txt
+          ${penv}/np_max install
+          ${penv}/tf_max install
+          ${penv}/jax_max install
+          ${penv}/torch_max install
+      - name: Run benchmarks
+        run: |
+          ${penv}/np_max ${run}/run_benchmark.py ${bex}/np_example.py ${res}
+          ${penv}/tf_max ${run}/run_benchmark.py ${bex}/tf_example.py ${res}
+          ${penv}/tf_max ${run}/run_benchmark.py ${bex}/tf_example.py --modifiers=no_compile ${res}
+          ${penv}/jax_max ${run}/run_benchmark.py ${bex}/jax_example.py ${res}
+          ${penv}/jax_max ${run}/run_benchmark.py ${bex}/jax_example.py --modifiers=no_jit ${res}
+          ${penv}/torch_max ${run}/run_benchmark.py ${bex}/torch_example.py ${res}
+      - name: Plot benchmarks
+        run: |
+          ${penv}/np_max ${run}/plot_benchmarks.py ${res}
+          mkdir -p ${plots}
+          mv ${res}/overhead.png ${plots}
+      - name: Commit new benchmark results
+        run: |
+          cd gh-pages
+          git add benchmark_results docs/benchmark_plots
+          git config --global user.email "none"
+          git config --global user.name "github-actions-bot"
+          git commit -m "Run benchmarks."
+          git push

.github/workflows/build_test_deploy.yml

@@ -0,0 +1,90 @@
+name: build_test_deploy
+
+on:
+  push:
+    branches-ignore:
+      - gh-pages
+  release:
+    types: [published]
+
+jobs:
+  test-base:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - run: curl -sSL https://install.python-poetry.org | python3 -
+      - run: poetry install
+      - run: poetry run task test
+
+  test-versions:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        framework: ["py", "np", "tf", "tfp", "jax", "torch"]
+        version: ["min", "max"]
+        include:
+          - version: "min"
+            python: "3.7"
+          - version: "max"
+            python: "3.10"
+
+    name: test-${{ matrix.framework }}-${{ matrix.version }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -r poetryenv_requirements.txt
+      - run: curl -sSL https://install.python-poetry.org | python3 -
+      - run: ./poetryenv poetryenvs/${{ matrix.framework }}_${{ matrix.version }} install
+      - run: ./poetryenv poetryenvs/${{ matrix.framework }}_${{ matrix.version }} run task test
+
+  all-tests:
+    needs: [test-base, test-versions]
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo ok
+
+  docs:
+    needs: all-tests
+    if: contains(fromJson('["refs/heads/main", "refs/heads/develop"]'), github.ref)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+          path: gh-pages
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - run: curl -sSL https://install.python-poetry.org | python3 -
+      - run: poetry install
+      - run: poetry run task docs
+      - name: Commit new documentation
+        run: |
+          branch=$(git symbolic-ref --short HEAD)
+          rm -rf gh-pages/docs/${branch}
+          mv docs_build gh-pages/docs/${branch}
+          cd gh-pages
+          git add docs
+          git config --global user.email "none"
+          git config --global user.name "github-actions-bot"
+          git commit -m "Build documentation."
+          git push
+
+  deploy:
+    needs: all-tests
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - run: curl -sSL https://install.python-poetry.org | python3 -
+      - run: poetry build
+      - run: poetry publish -u __token__ -p ${{ secrets.CHECK_SHAPES_PYPI_TOKEN }}

.gitignore

@@ -69,7 +69,8 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs_build/
+docs_test/
 
 # PyBuilder
 target/

CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+title: check_shapes
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Jesper
+    family-names: Nielsen
+    email: [email protected]
+    affiliation: Secondmind
+repository-code: 'https://github.com/GPflow/check_shapes'
+abstract: >-
+  A library for annotating and checking tensor
+  shapes.
+license: Apache-2.0

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to `check_shapes`
+
+This file contains notes for potential contributors to `check_shapes`, as well as some notes that may be helpful for maintenance.
+
+## Project scope
+
+The aim of `check_shapes` is to annotate and check the shapes of tensors. There are many other pre- and post conditions one could check, but to keep the scope reasonable we will limit ourselves to tensor shapes.
+
+We welcome contributions to `check_shapes`. If you would like to contribute a feature, please raise discussion via a GitHub issue, to discuss the suitability of the feature within `check_shapes`. If the feature is outside the envisaged scope, we can still link to a separate project in our Readme.
+
+### I have this big feature/extension I would like to add...
+
+Due to limited scope we may not be able to review and merge every feature, however useful it may be. Particularly large contributions or changes to core code are harder to justify against the scope of the project or future development plans. We recommend discussing a possible contribution in an issue before work begins. This should give an indication to how broadly it is supported to bring it into the codebase.
+
+## Code quality requirements
+
+- Code must be covered by tests. We use the [pytest](https://docs.pytest.org/) framework.
+- The code must be documented. We use *reST* in docstrings. *reST* is a [standard way of documenting](http://docs.python-guide.org/en/latest/writing/documentation/) in python.
+  Missing documentation leads to ambiguities and difficulties in understanding future contributions and use cases.
+- Use [type annotations](https://docs.python.org/3/library/typing.html). Type hints make code cleaner and _safer_ to some extent.
+- Python code should generally follow the *PEP8* style. We use some custom naming conventions (see below) to have our notation follow the Gaussian process literature. Use `pylint` and `mypy` for formatting and _type checking_.
+- Practise writing good code as far as is reasonable. Simpler is usually better. Reading the existing codebase should give a good idea of the expected style.
+- `check_shapes` uses [black](https://github.com/psf/black) and [isort](https://pycqa.github.io/isort/) for formatting.
+- You can use `poetry run task format_and_test` to check that your code follows the above requirements.
+
+## Pull requests
+
+If you think that your contribution falls within the project scope (see above) please submit a Pull Request (PR) to our GitHub page.
+(GitHub provides extensive documentation on [forking](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) and [pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests).)
+
+In order to maintain code quality, and make life easy for the reviewers, please ensure that your PR:
+
+- Only fixes one issue or adds one feature.
+- Makes the minimal amount of changes to the existing codebase.
+- Is testing its changes.
+- Passes all checks (formatting, types, tests - you can run them all locally using `poetry run task test` from the `check_shapes` root directory).
+
+All code goes through a PR; there are no direct commits to the `main` and `develop` branches.
+
+## Version numbering
+
+The main purpose of versioning `check_shapes` is user convenience.
+
+We use the [semantic versioning scheme](https://semver.org/). The semver implies `MAJOR.MINOR.PATCH` version scheme, where `MAJOR` changes when there are incompatibilities in API, `MINOR` means adding functionality without breaking existing API and `PATCH` presumes the code update has backward compatible bug fixes.
+
+When incrementing the version number, this has to be reflected in `./pyproject.toml`.

CONTRIBUTORS.md

@@ -0,0 +1,7 @@
+# List of contributors to `check_shapes`
+
+Because GitHub's [graph of contributors](http://github.com/GPflow/GPflow/graphs/contributors) does not necessarily include all contributors, this file contains a list of all contributors, added by date of first contribution.
+
+[@jesnie](https://github.com/jesnie)
+
+Add yourself when you first contribute to `check_shapes`'s code, tests, or documentation!

HOWTO_RELEASE.md

@@ -0,0 +1,34 @@
+# How to make a new `check_shapes` release
+
+1. Bump the version numbers in the `develop` branch, in *BOTH* the
+   [`pyproject.toml`](https://github.com/GPflow/check_shapes/blob/develop/pyproject.toml) file
+   and the
+   [`__init__`](https://github.com/GPflow/check_shapes/blob/develop/check_shapes/__init__.py).
+
+2. Update [RELEASE.md](https://github.com/GPflow/check_shapes/blob/develop/RELEASE.md).
+   - Make sure it contains up-to-date release notes for the next release.
+     * They should cover all changes, that are visible to library userso on the `develop` branch
+       since the most recent release.
+     * They should make clear to users whether they might benefit from this release and what
+       backwards incompatibilities they might face.
+   - Make sure the release version matches what you were setting elsewhere.
+   - Make a new copy of the template, to prepare for the next release.
+
+3. Create a release PR from `develop` to `main`.
+   - **Make a merge commit. DO NOT SQUASH-MERGE.**
+   - If you squash-merge, `main` will be *ahead* of develop (by the squash-merge commit). This
+     means we’ll end up with merge conflicts at the following release!
+
+4. Go to the [release page on GitHub](https://github.com/GPflow/check_shapes/releases/new) and
+   create a release for a tag “v{VERSION}” (e.g., for version 2.1.3 the tag needs to be `v2.1.3`) to
+   `main` branch. Copy the release notes into the description field!
+
+5. You are almost done now! Go to https://github.com/GPflow/check_shapes/actions and monitor the
+   tests for your newly-created release passed and the job for pushing the pip package succeeded.
+   GitHub Actions are triggered by the publication of the release above.
+
+6. Take a break; wait until the new release
+   [shows up on PyPi](https://pypi.org/project/check_shapes/#history).
+
+
+Done done! Go and celebrate our hard work :)

README.md

@@ -48,4 +48,6 @@ To check you installation run our tests:
 
 ```bash
 poetry run task test
-```
+```
+
+For testing with different versions of Python and dependencies, see the `poetryenv` script.

RELEASE.md

@@ -0,0 +1,103 @@
+Release notes for all past releases are available in the ['Releases' section](https://github.com/GPflow/check_shapes/releases) of the `check_shapes` Repo. [HOWTO_RELEASE.md](HOWTO_RELEASE.md) explains just that.
+
+# Release x.y.z (template for future releases)
+
+<INSERT SMALL BLURB ABOUT RELEASE FOCUS AREA AND POTENTIAL TOOLCHAIN CHANGES>
+
+## Breaking Changes
+
+* <DOCUMENT BREAKING CHANGES HERE>
+* <THIS SECTION SHOULD CONTAIN API AND BEHAVIORAL BREAKING CHANGES>
+
+## Known Caveats
+
+* <CAVEATS REGARDING THE RELEASE (BUT NOT BREAKING CHANGES).>
+* <ADDING/BUMPING DEPENDENCIES SHOULD GO HERE>
+* <KNOWN LACK OF SUPPORT ON SOME PLATFORM SHOULD GO HERE>
+
+## Major Features and Improvements
+
+* <INSERT MAJOR FEATURE HERE, USING MARKDOWN SYNTAX>
+* <IF RELEASE CONTAINS MULTIPLE FEATURES FROM SAME AREA, GROUP THEM TOGETHER>
+
+## Bug Fixes and Other Changes
+
+* <SIMILAR TO ABOVE SECTION, BUT FOR OTHER IMPORTANT CHANGES / BUG FIXES>
+* <IF A CHANGE CLOSES A GITHUB ISSUE, IT SHOULD BE DOCUMENTED HERE>
+* <NOTES SHOULD BE GROUPED PER AREA>
+
+## Thanks to our Contributors
+
+This release contains contributions from:
+
+<INSERT>, <NAME>, <HERE>, <USING>, <GITHUB>, <HANDLE>
+
+
+# Release 0.3.0 (next upcoming release in progress)
+
+<INSERT SMALL BLURB ABOUT RELEASE FOCUS AREA AND POTENTIAL TOOLCHAIN CHANGES>
+
+## Breaking Changes
+
+* <DOCUMENT BREAKING CHANGES HERE>
+* <THIS SECTION SHOULD CONTAIN API AND BEHAVIORAL BREAKING CHANGES>
+
+## Known Caveats
+
+* <CAVEATS REGARDING THE RELEASE (BUT NOT BREAKING CHANGES).>
+* <ADDING/BUMPING DEPENDENCIES SHOULD GO HERE>
+* <KNOWN LACK OF SUPPORT ON SOME PLATFORM SHOULD GO HERE>
+
+## Major Features and Improvements
+
+* <INSERT MAJOR FEATURE HERE, USING MARKDOWN SYNTAX>
+* <IF RELEASE CONTAINS MULTIPLE FEATURES FROM SAME AREA, GROUP THEM TOGETHER>
+
+## Bug Fixes and Other Changes
+
+* <SIMILAR TO ABOVE SECTION, BUT FOR OTHER IMPORTANT CHANGES / BUG FIXES>
+* <IF A CHANGE CLOSES A GITHUB ISSUE, IT SHOULD BE DOCUMENTED HERE>
+* <NOTES SHOULD BE GROUPED PER AREA>
+
+## Thanks to our Contributors
+
+This release contains contributions from:
+
+<INSERT>, <NAME>, <HERE>, <USING>, <GITHUB>, <HANDLE>
+
+
+# Release 0.2.0
+
+This release makes `check_shapes` independent of the underlying framework.
+
+## Major Features and Improvements
+
+* Made `check_shapes` independent of tensor framework:
+  - Made NumPy optional.
+  - Made TensorFlow optional.
+  - Made TensorFlow-Probability optional.
+  - Added support for JAX.
+  - Added support for PyTorch.
+* Added benchmarks and documentation of overhead imposed by `check_shapes`.
+
+## Bug Fixes and Other Changes
+
+* Fixed bug related to `tf.saved_model` and methods wrapped in `@check_shapes`.
+* Added support for TensorFlow-Probability `_TensorCoercible` objects.
+
+## Thanks to our Contributors
+
+This release contains contributions from:
+
+jesnie
+
+
+# Release 0.1.0
+
+Initial import from [GPflow](https://github.com/GPflow/GPflow) and experimental release.
+
+## Thanks to our Contributors
+
+This release contains contributions from:
+
+jesnie