===========
Development
===========
Getting started
---------------
**Pharaoh** is an open source project initiated by `Infineon Technologies <https://www.infineon.com/>`_
and we welcome contributions of all forms.
The sections below will help you get started with development, testing, and documentation.
This document is meant to get you setup to work on Pharaoh and to act as a guide and reference to the development
setup. If you face any issues during this process, please `create an issue
<https://github.com/Infineon/pharaoh-dev/issues/new?title=Trouble+with+development+environment>`_
about it on the issue tracker.
Setup
~~~~~
To work on it, you'll need:
- **Source code**: available on :gh_repo:`GitHub <Infineon/pharaoh-dev>`. You can use ``git`` to clone the repository:
.. code-block:: shell
git clone https://github.com/Infineon/pharaoh-dev.git
cd pharaoh-dev
- **Python interpreter**: We recommend using ``CPython``. You can use
`this guide <https://realpython.com/installing-python/>`_ to set it up.
- :pypi:`tox`: to automatically get the projects development dependencies and run the test suite. We recommend
installing it using `pipx <https://pipxproject.github.io/pipx/>`_.
Running from source tree
~~~~~~~~~~~~~~~~~~~~~~~~
The easiest way to do this is to generate a development environment:
.. code-block:: shell
tox devenv -e py venv
This will install a virtualenv using the same Python version as under which ``tox`` is installed. Alternatively you can
specify a specific version of Python by using the ``pyNN`` format, such as: ``py311``, etc.
.. code-block:: shell
tox devenv -e py311 venv
Set ``venv/Scripts/python.exe`` (Windows) or ``venv/bin/python`` (Linux) as project interpreter in your IDE
and you're good to go.
.. seealso:: `tox devenv <https://tox.wiki/en/latest/cli_interface.html#tox-devenv-(d)>`_
Running tests
~~~~~~~~~~~~~
Pharaoh's tests are written using the :pypi:`pytest` test framework.
:pypi:`tox` is used to automate the setup and execution of Pharaoh's tests.
To run tests locally execute:
.. code-block:: shell
tox -e py
This will run the test suite for the same Python version as under which ``tox`` is installed. Alternatively you can
specify a specific version of Python by using the ``pyNN`` format, such as: ``py38``, ``pypy3``, etc.
``tox`` has been configured to forward any additional arguments it is given to ``pytest``. This enables the use of
pytest's `rich CLI <https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run>`_. As an example,
you can select tests using the various ways that pytest provides:
.. code-block:: shell
# Using markers
tox -e py -- -m "not slow"
# Using keywords
tox -e py -- -k "test_extra"
Running linters and code formatters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pharaoh uses :pypi:`pre-commit` for managing linting and formatting of the codebase.
``pre-commit`` performs various checks on all files in Pharaoh and uses tools that help following a consistent
code style within the codebase. To execute the pre-commit hooks manually execute:
.. code-block:: shell
tox -e fix
Code style guide
~~~~~~~~~~~~~~~~
- First and foremost, the linters configured for the project must pass; this generally means following PEP-8 rules,
as codified by: ``ruff``, ``ruff-format``.
- The supported Python versions (and the code syntax to use) are listed in the ``pyproject.toml`` file
in the ``project/requires-python`` entry.
- All code (tests too) must be type annotated as much as required by ``mypy``.
Check this using ``tox -e type``.
- We use a line length of 120.
- All function (including test) names must follow PEP-8, so they must be fully snake cased. All classes are upper
camel-cased.
- Prefer f-strings instead of the ``str.format`` method.
- Tests should contain as little information as possible but do use descriptive variable names within it.
Building documentation
~~~~~~~~~~~~~~~~~~~~~~
Pharaoh's documentation is built using :pypi:`Sphinx`. The documentation is written in reStructuredText. To build it
locally, run:
.. code-block:: shell
tox -e docs
The built documentation can be found in the ``dist/docs`` folder and may be viewed by opening ``index.html`` within
that folder.
Contributing
-------------
Submitting pull requests
~~~~~~~~~~~~~~~~~~~~~~~~
Submit pull requests (PRs) against the ``main`` branch, providing a good description of what you're doing and why. You
must have legal permission to distribute any code you contribute to Pharaoh and it must be available under the MIT
License.
Provide tests that cover your changes and run the tests locally first.
Pharaoh supports multiple Python versions and operating systems.
Any pull request must consider and work on all these platforms.
Pull requests should be small to facilitate review. Keep them self-contained, and limited in scope. Studies have shown
that review quality falls off as patch size grows. In particular, pull requests must not be treated as
"feature branches", with ongoing development work happening within the PR. Instead, the feature should be broken up into
smaller, independent parts which can be reviewed and merged individually.
Additionally, avoid including "cosmetic" changes to code that is unrelated to your change, as these make reviewing the
PR more difficult. Examples include re-flowing text in comments or documentation, or addition or removal of blank lines
or whitespace within lines. Such changes can be made separately, as a "formatting cleanup" PR, if needed.
Automated testing
~~~~~~~~~~~~~~~~~
All pull requests and merges to the ``main`` branch are tested using :gh:`GitHub Actions <features/actions>`
(configured by ``matrix_tests.yml`` file inside the ``.github/workflows`` directory).
You can find the status and the results to the CI runs for your PR on GitHub's Web UI for the pull request.
You can also find links to the CI services' pages for the specific builds in the form of "Details" links,
in case the CI run fails and you wish to view the output.
To trigger CI to run again for a pull request, you can close and open the pull request or submit another change to the
pull request. If needed, project maintainers can manually trigger a restart of a job/build.
Changelog entries
~~~~~~~~~~~~~~~~~
The ``changelog.rst`` file is currently manually curated and all relevant changes must be accompanied by a changelog entry.
To add an entry to the changelog, first you need to have created an issue describing the change you want to make. A pull
request itself *may* function as such, but it is preferred to have a dedicated issue (for example, in case the PR ends
up rejected due to code quality reasons).
There is no need to create an issue for trivial changes, e.g. for typo fixes.
Contents of a changelog entry
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The content of this file is reStructuredText formatted text that will be used as the content of the changelog entry.
You do not need to reference the issue or PR numbers here as towncrier will automatically add a reference to all of the
affected issues when rendering the changelog.
In order to maintain a consistent style in the ``changelog.rst`` file, it is preferred to keep the entries to the
point, in sentence case, shorter than 120 characters and in an imperative tone -- an entry should complete the sentence
``This change will …``. In rare cases, where one line is not enough, use a summary line in an imperative tone followed
by a blank line separating it from a description of the feature/change in one or more paragraphs, each wrapped at 120
characters. Remember that a changelog entry is meant for end users and should only contain details relevant to an end
user.
Creating a new release
~~~~~~~~~~~~~~~~~~~~~~
Releases are currently created using GitHub's release functionality.
Prior to creating a release on GitHub make sure the target version in the changelog is correct
and then `draft a new release <https://github.com/Infineon/pharaoh-dev/releases/new>`_ with the target version number
according to `Semantic Versioning <https://semver.org/>`_.
.. _current-maintainers:
Current maintainers
^^^^^^^^^^^^^^^^^^^
- :user:`Johannes Loibl <johannesloibl>`
- :user:`Axel Krüner <axel-kah>`