Developer Start Guide#
Looking for an idea for a first contribution? Check the GitHub issues.
We recommend creating an issue to discuss proposed changes before making them. This is a good way to make sure that proposed changes will be accepted.
The Theano Google group is also relevant to (early) Aesara versions: theano-dev.
Requirements for Quality Contributions#
The following are requirements for a quality pull request (PR)/contribution:
All code should be accompanied by quality unit tests that provide complete coverage of the features added.
There is an informative high-level description of the changes, or a reference to an issue describing the changes.
The description and/or commit messages reference any relevant GitHub issues.
The commit messages follow these guidelines.
The commits correspond to relevant logical changes, and there are no commits that fix changes introduced by other commits in the same branch/BR.
There are tests, implemented within the pytest framework, covering the changes introduced by the PR.
Type hints are added where appropriate.
Don’t worry, your PR doesn’t need to be in perfect order to submit it. As development progresses and/or reviewers request changes, you can always rewrite the history of your feature/PR branches.
If your PR is an ongoing effort and you would like to involve us in the process, simply make it a draft PR.
When you submit a PR, your changes will automatically be tested via our continuous integration (CI). Just because the tests run automatically does not mean you shouldn’t run them yourself to make sure everything is all right. You can run only the portion you are modifying to go faster and have CI make sure there are no broader problems.
To run the test suite with the default options, see How to test that Aesara works properly.
Documentation and docstrings#
The documentation and the API documentation are generated using Sphinx.
A Docstring Example#
Here is an example on how to add a docstring to a class.
from aesara.graph.basic import Variable
from aesara.graph.op import Op
"""Double each element of a tensor.
this is a test note
`Elemwise`: This functionality is already available; just execute
``x * 2`` with ``x`` being an Aesara variable.
def make_node(self, x: Variable):
"""Construct an `Apply` node for this `Op`.
Installation and configuration#
This will create your own clone of the Aesara project on GitHub’s servers. It is customary to assign this Git remote the name “origin”, and the official Aesara repository the name “upstream”.
Create a local copy#
Clone your fork locally with
git clone firstname.lastname@example.org:YOUR_GITHUB_LOGIN/Aesara.git
For this URL to work, you must set your public SSH keys inside your GitHub account setting.
From your local repository, your fork on GitHub will be called “origin” by default.
Next, create a remote entry for the original (i.e. upstream) Aesara repository with the following:
git remote add upstream git://github.com/aesara-devs/aesara.git
You can choose a name other than “upstream” to reference the official Aesara repository.
We also have to pull the necessary tags like so:
git fetch -t --all
If an error along the lines of
errno=Operation timed out occurs here, then you
may need to run
git remote set-url upstream https://github.com/aesara-devs/aesara.git
git fetch -t --all
Setting up the your local development environment#
You will need to create a virtual environment and install the project requirements within it.
The recommended approach is to install conda and create a virtual environment in the project directory:
For computers using an ARM processor, replace the
environment.yml below with
conda env create -n aesara-dev -f environment.yml
conda activate aesara-dev
Afterward, you can install the development dependencies:
pip install -r requirements.txt
pre-commit needs to be configured so that the linting and code quality
checks are performed before each commit:
The virtual environment will need to be activated in any environment (e.g. shells, IDEs, etc.) that plans to run the Aesara tests or add commits to the project repository.
You can now test your environment/code by running
pytest in the project’s root
directory. See How to test that Aesara works properly for more information about testing.
Contributing to the documentation#
To contribute to the documentation, first follow the instructions in the previous section. Afterward, you can install the documentation dependencies in the virtual environment you created:
pip install -r requirements-rtd.txt
You can now build the documentation from the root of the project with:
Afterward, you can go to
html/index.html and navigate the changes in a browser. One way to do this is to go to the
html directory and run:
python -m http.server
Do not commit the `html` directory. The documentation is built automatically.
Other tools that might help#
cProfile: Time profiler that work at function level
line_profiler: Line-by-line profiler
memory_profiler: A memory profiler
runsnake: GUI for cProfile (time profiler) and Meliae (memory profiler)
Guppy: Supports object and heap memory sizing, profiling, and debugging
hub: A tool that adds GitHub commands to the git command line
git pull-requests: Another command line tool for