If you are planning to develop GLASS, or want to use the latest commit of GLASS on your local machine, you might want to install it from the source. This installation is not recommended for users who want to use the stable version of GLASS. The page below describes how to build, test, and develop GLASS.
The developer installation of GLASS comes with several optional dependencies -
test: installs extra packages used in tests and the relevant testing framework/pluginsdocs: installs documentation related dependenciesexamples: installs libraries used in the examples and a few notebook related dependencies
These options can be used with pip with the editable (-e) mode of
installation in the following way -
pip install -e ".[docs,test]"GLASS uses a set of pre-commit hooks and the pre-commit.ci bot to format,
lint, and prettify the codebase. The hooks can be installed locally using -
pre-commit installThis would run the checks every time a commit is created locally. The checks will only run on the files modified by that commit, but the checks can be triggered for all the files using -
pre-commit run --all-filesIf you would like to skip the failing checks and push the code for further
discussion, use the --no-verify option with git commit.
GLASS is tested using pytest and pytest-doctestplus. pytest is
responsible for testing the code, whose configuration is available in
pyproject.toml.
pytest-doctestplus is responsible for testing the examples available in every
docstring, which prevents them from going stale. Additionally, GLASS also uses
pytest-cov (and Coveralls) to calculate/display the
coverage of these unit tests.
The tests can be executed using the test dependencies of GLASS in the
following way -
python -m pytest --cov --doctest-plusOne can specify a particular array backend for testing by setting the
GLASS_ARRAY_BACKEND environment variable. The default array backend is NumPy.
GLASS can be tested with every supported array library available in the
environment by setting GLASS_ARRAY_BACKEND to all. The testing framework
only installs NumPy automatically; hence, remaining array libraries should
either be installed manually or developers should use Nox.
# run tests using numpy
python -m pytest
GLASS_ARRAY_BACKEND=numpy python -m pytest
# run tests using array_api_strict (should be installed manually)
GLASS_ARRAY_BACKEND=array_api_strict python -m pytest
# run tests using jax (should be installed manually)
GLASS_ARRAY_BACKEND=jax python -m pytest
# run tests using every supported array library available in the environment
GLASS_ARRAY_BACKEND=all python -m pytestMoreover, one can mark a test to be compatible with the array API standard by
decorating it with @array_api_compatible. This will parameterize the test to
run on every array library specified through GLASS_ARRAY_BACKEND -
import types
from tests.conftest import array_api_compatible
@array_api_compatible
def test_something(xp: types.ModuleType):
# use `xp.` to access the array library functionality
...GLASS's documentation is mainly written in the form of
docstrings and
reStructurredText.
The docstrings include the description, arguments, examples, return values, and
attributes of a class or a function, and the .rst files enable us to render
this documentation on GLASS's documentation website.
GLASS primarily uses Sphinx for
rendering documentation on its website. The configuration file (conf.py) for
sphinx can be found
under the docs folder.
The documentation is deployed on https://readthedocs.io
here.
Ideally, with the addition of every new feature to GLASS, documentation should
be added using comments, docstrings, and .rst files.
The documentation is located in the docs folder of the main repository. This
documentation can be generated using the docs dependencies of GLASS in the
following way -
cd docs/
make clean
make htmlThe commands executed above will clean any existing documentation build and
create a new build under the docs/_build folder. You can view this build in
any browser by opening the index.html file.
To release a new version of GLASS, there should be a commit that includes the following changes:
- The changes since the last release are added to the changelog
under a section titled
[yyyy.mm] (DD Mon YYYY). A new link to the changeset is added at the bottom of the file. - The release notes are updated with the new version. The release notes should translate the changelog entries into prose that can be understood by non-developer users of the code. If there are breaking changes, a release note should explain what the changes mean for existing code.
Once these changes are merged into the main branch, a new release with title
glass yyyy.mm should be created in the GitHub repository. The description of
the release should be a copy of its release note.
Creating the release will automatically start the build process that uploads Python packages for the new version to PyPI.
If any GLASS extension packages depend on the new release, new versions of these packages should be produced as soon as the new release is published to PyPI.
GLASS follows CalVer. There is no difference between releases that increment the year and releases that increment the month; in particular, releases that increment the month may introduce breaking changes.
The current version number is automatically inferred from the last release (i.e., git tag), subsequent unreleased commits, and local changes, if any.
The target is to have a new GLASS release once there are significant changes to the code's functionality.
GLASS supports running various critical commands using
nox to make them less intimidating for new
developers. All of these commands (or sessions in the language of nox) -
lint, tests, coverage, doctests, docs, and build - are defined in
noxfile.py.
nox can be installed via pip using -
pip install noxThe default sessions (lint and tests) can be executed using -
noxA particular session (for example tests) can be run with nox on all
supported Python versions using -
nox -s testsOnly tests, coverage, and the doctests session run on all supported Python
versions by default.
To specify a particular Python version (for example 3.13), use the following
syntax -
nox -s tests-3.13One can specify a particular array backend for testing by setting the
GLASS_ARRAY_BACKEND environment variable. The default array backend is NumPy.
GLASS can be tested with every supported array library by setting
GLASS_ARRAY_BACKEND to all.
# run tests using numpy
nox -s tests-3.13
GLASS_ARRAY_BACKEND=numpy nox -s tests-3.13
# run tests using array_api_strict
GLASS_ARRAY_BACKEND=array_api_strict nox -s tests-3.13
# run tests using jax
GLASS_ARRAY_BACKEND=jax nox -s tests-3.13
# run tests using every supported array library
GLASS_ARRAY_BACKEND=all nox -s tests-3.13The following command can be used to deploy the docs on localhost -
nox -s docs -- serveThe nox environments created for each type of session on the first run is
saved under .nox/ and reused by default.
Every change to the repository should come out of an issue where the change is discussed.
Pull requests should always follow from the discussion in an existing issue. The only exception are minor, obvious changes such as fixing typos in the documentation.
The discussion in a pull request should only be about the low-level details of its implementation. All high-level, conceptual discussion belongs to the issue to which the pull request refers.
Pull requests to the main branch should have titles of the following form:
gh-<issue-number>: Subject lineThe body of the pull request should contain a description of the changes, and any relevant details or caveats of the implementation.
The pull request should not repeat or summarise the discussion of its associated
issue. Instead, it should link to the issue using git's so-called "trailers".
These are lines of the form key: value which are at the end of the pull
request description, separated from the message body by a blank line.
To generically refer to an issue without any further action, use Refs and one
or more GitHub issue numbers:
Refs: #12
Refs: #25, #65To indicate that the pull request shall close an open issue, use Closes and a
single GitHub issue number:
Closes: #17Changelog entries are collected using the following trailers, and later parsed into the changelog for the next release:
Added: Some new feature
Changed: Some change in existing functionality
Deprecated: Some soon-to-be removed feature
Removed: Some now removed feature
Fixed: Some bug fix
Security: Some vulnerability was fixed
You can use any of the other common git trailers. In particular, you can use
Cc to notify others of your pull request via their GitHub user names:
Cc: @octocat