How to contribute¶
First, thanks for considering contributing to Astrality, that means a lot! Here we describe how you can help out, either by improving the documentation, submitting issues, or creating pull requests.
If you end up contributing, please consider adding yourself to the file
Bug reports and feature requests¶
Improving the documentation¶
If you find something you would like to improve in the documentation, follow these steps:
- Navigate to the page that you would like to edit on https://astrality.readthedocs.io.
- Press the “Edit on GitHub” link in the upper right corner.
- Press the “pencil” edit icon to the right of the “History” button.
- Make the changes you intended.
- Write a title and description for your change on the bottom of the page.
- Select the radio button marked as: “Create a new branch for this commit and start a pull request”.
- Press “Propose file change”.
The documentation is written in the “RestructuredText” markup language. If this is unfamiliar to you, take a look at this RST cheatsheet for more information.
Getting up and running¶
Cloning the repository¶
First we need to clone the repository. Open your terminal and navigate to the directory you wish to place project directory and run:
git clone https://github.com/jakobgm/astrality cd astrality
Astrality runs on
python3.6, so you need to ensure that you have it
installed. If you have no specific preferred way of installing software on your
computer, you can download and install it from here. Alternatively, if you use brew on
MacOS, you can install it by running:
brew install python3
Or on ArchLinux:
sudo pacman -S python
Installing dependencies into a virtual environment¶
You should create a separate python3.6 “virtual environment” exclusively for Astrality. If this is new to you, take a look at the official virtualenv tutorial.
A quick summation:
python3.6 -m venv astrality-env source astrality-env/bin/activate
Your terminal prompt should now show the name of the activated virtual
environment, for example
(astrality-env) $ your_commands_here.
You can double check your environment by running
Later you can deactivate it by running
deactivate or restarting your
The activated virtual environment is necessary in order to run the developer
version of Astrality, including the test suite.
Now you can install all the developer dependencies of Astrality into the virtual environment by running:
pip3 install -r requirements.txt
You should now make sure that the environment variable
PYTHONPATH is set to
the root directory of the repository. Check it by running:
$ echo $PYTHONPATH /home/jakobgm/dev/astrality
/home/jakobgm/dev/astrality being whatever makes sense on your system.
If the value is incorrect you should run the following from the repository
Running the developer version of Astrality¶
You should now be able to run the developer version of Astrality by running the following command:
The python code in Astrality follows some conventions which we will describe here.
The structure of the code base¶
A brief outline Astrality’s code base is provided in the API documentation, and is recommended reading for any new contributor.
Astrality strives for 100% test coverage, and all new lines of code should preferably be covered by tests. That being said, if testing is unfamiliar to you, submitting code without test coverage is better than no code at all.
You can run the test suite from the root of the repository by running:
For now, it is important that you run pytest from the root of the
repository, else you will get a whole lot of
Additionally, there are some tests which are hidden behind the
flag, as some tests are slow due to writing files to disk and running certain
shell commands. These slow tests can be run by writing:
If this feels intimidating, do not worry. We are happy to help guide you along if you encounter any issues with testing, so please submit pull requests even if the test suite fails for some reason.
Astrality’s code base heavily utilizes the new static type annotations available in python3.6.
The correctness of the type annotations are ensured by using mypy. You can check for type errors by running the following command from the repository root:
mypy is a part of the test suite, enabled by the pytest-mypy plugin.
Therefore, if the test suite passes,
mypy must also be satisfied with your
All non-testing code should be completely type annotated, as strictly as possible. If this is new to you, or if you want to learn more, I recommend reading mypy documentation.
The offer to help with testing also holds for type annotations of course!
Although this is mainly a matter of taste, running tests continuously while writing code is a great feedback mechanism.
pytest-watch should be already be installed on your system as part of
Astrality’s developer dependencies. You can use it to rerun the test suite
every time you save any
*.py file within the repository.
You can run it in a separate terminal by running:
It is often useful to run
pytest-watch in verbose mode, stop on first test
failure, and only run one specific test file at a time. You can do all this by
ptw -- -vv -x astrality/tests/test_compiler.py
If you end up breaking any behaviour during development, it should often be reported by the test suite. Breaking tests will often lead you in the correct direction for fixing the problem.
Some tests might be a bit too brittle, so if you change any underlying data structures it might break some badly written test(s). Sometimes the correct thing to do is to simply delete the failing test. Just ask if you are unsure.
You can also look at the logging output of Astrality in order to pinpoint
possible reasons for any weird behaviour. You can set the logging level of astrality
by setting the environment variable
ASTRALITY_LOGGING_LEVEL to an
appropriate value, for example:
# Set the appropiate logging level export ASTRALITY_LOGGING_LEVEL=DEBUG # Run the CLI entrypoint ./bin/astrality
If you submit a bug report, we appreciate if you include the standard output of
Astrality run with
We use the python source code checker flake8 to help us maintain a consistent
style across the code base. It runs automatically as part of our
You can lint your code locally by running
flake8 . from the root of the
flake8 into your workflow is recommended, there are plugins
available for most popular IDEs
You can instruct git to ensure flake8 compliance before every commit by running
git config --bool flake8.strict true from your shell.
In addition to this, some additional styling conventions are applied to the project:
String literals should use single quotes. With other words:
'this is a string'instead of
"this is a string".
Try to use keyword arguments when calling functions, unless it is extremely clear from context.
Function arguments split over several lines should use trailing commas. With other words, we prefer to write code like this:
compile_template( template=template, target=target, )
Instead of this:
compile_template( template=template, target=target )
These conventions are mainly enforced in order to stay consistent for choices
PEP 8 do not tell us what to do.
You can run a local instance of the documentation by running:
cd docs sphinx-autobuild . _build
The entire documentation should now be available on http://127.0.0.1:8000.
When you edit the documentation files placed with
docs, your web browser
should automatically refresh the website with the new content!