-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
267 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,242 @@ | ||
| Developer's guide | ||
| ================= | ||
|
|
||
| .. note:: | ||
|
|
||
| The https://learn.scientific-python.org webpages are an extremely valuable | ||
| learning resource for Python software developer. The reader is referred to | ||
| that for any detail not covered in the following guide. | ||
|
|
||
| The following rules and conventions have been established for the package | ||
| development and are enforced throughout the entire code base. Merge requests | ||
| that do not comply to the following directives will be rejected. | ||
|
|
||
| To start developing *legend-daq2lh5*, fork the remote repository to your personal | ||
| GitHub account (see `About Forks | ||
| <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks>`_). | ||
| If you have not set up your ssh keys on the computer you will be working on, | ||
| please follow `GitHub's instructions | ||
| <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`_. | ||
| Once you have your own fork, you can clone it via | ||
| (replace "yourusername" with your GitHub username): | ||
|
|
||
| .. code-block:: console | ||
| $ git clone [email protected]:yourusername/legend-daq2lh5.git | ||
| All extra tools needed to develop *legend-daq2lh5* are listed as optional | ||
| dependencies and can be installed via pip by running: | ||
|
|
||
| .. code-block:: console | ||
| $ cd legend-daq2lh5 | ||
| $ pip install -e '.[all]' # single quotes are not needed on bash | ||
| .. important:: | ||
|
|
||
| Pip's ``--editable | -e`` flag let's you install the package in "developer | ||
| mode", meaning that any change to the source code will be directly | ||
| propagated to the installed package and importable in scripts. | ||
|
|
||
| .. tip:: | ||
|
|
||
| It is strongly recommended to work inside a virtual environment, which | ||
| guarantees reproductibility and isolation. For more details, see | ||
| `learn.scientific-python.org | ||
| <https://learn.scientific-python.org/development/tutorials/dev-environment/>`_. | ||
|
|
||
| Code style | ||
| ---------- | ||
|
|
||
| * All functions and methods (arguments and return types) must be | ||
| `type-annotated <https://docs.python.org/3/library/typing.html>`_. Type | ||
| annotations for variables like class attributes are also highly appreciated. | ||
| * Messaging to the user is managed through the :mod:`logging` module. Do not | ||
| add :func:`print` statements. To make a logging object available in a module, | ||
| add this: | ||
|
|
||
| .. code-block:: python | ||
| import logging | ||
| log = logging.getLogger(__name__) | ||
| at the top. In general, try to keep the number of :func:`logging.debug` calls | ||
| low and use informative messages. :func:`logging.info` calls should be | ||
| reserved for messages from high-level routines and very sporadic. Good code | ||
| is never too verbose. | ||
| * If an error condition leading to undefined behavior occurs, raise an | ||
| exception. try to find the most suitable between the `built-in exceptions | ||
| <https://docs.python.org/3/library/exceptions.html>`_, otherwise ``raise | ||
| RuntimeError("message")``. Do not raise ``Warning``\ s, use | ||
| :func:`logging.warning` for that and don't abort the execution. | ||
| * Warning messages (emitted when a problem is encountered that does not lead to | ||
| undefined behavior) must be emitted through :func:`logging.warning` calls. | ||
|
|
||
| A set of `pre-commit <https://pre-commit.com>`_ hooks is configured to make | ||
| sure that *legend-daq2lh5* coherently follows standard coding style conventions. | ||
| The pre-commit tool is able to identify common style problems and automatically | ||
| fix them, wherever possible. Configured hooks are listed in the | ||
| ``.pre-commit-config.yaml`` file at the project root folder. They are run | ||
| remotely on the GitHub repository through the `pre-commit bot | ||
| <https://pre-commit.ci>`_, but should also be run locally before submitting a | ||
| pull request: | ||
|
|
||
| .. code-block:: console | ||
| $ cd legend-daq2lh5 | ||
| $ pip install '.[test]' | ||
| $ pre-commit run --all-files # analyse the source code and fix it wherever possible | ||
| $ pre-commit install # install a Git pre-commit hook (strongly recommended) | ||
| For a more comprehensive guide, check out the `learn.scientific-python.org | ||
| documentation about code style | ||
| <https://learn.scientific-python.org/development/guides/style/>`_. | ||
|
|
||
| Testing | ||
| ------- | ||
|
|
||
| * The *legend-daq2lh5* test suite is available below ``tests/``. We use `pytest | ||
| <https://docs.pytest.org>`_ to run tests and analyze their output. As | ||
| a starting point to learn how to write good tests, reading of `the | ||
| relevant learn.scientific-python.org webpage | ||
| <https://learn.scientific-python.org/development/guides/pytest/>`_ is | ||
| recommended. | ||
|
|
||
| * Unit tests are automatically run for every push event and pull request to the | ||
| remote Git repository on a remote server (currently handled by GitHub | ||
| actions). Every pull request must pass all tests before being approved for | ||
| merging. Running the test suite is simple: | ||
|
|
||
| .. code-block:: console | ||
| $ cd legend-daq2lh5 | ||
| $ pip install '.[test]' | ||
| $ pytest | ||
| * Additionally, pull request authors are required to provide tests with | ||
| sufficient code coverage for every proposed change or addition. If necessary, | ||
| high-level functional tests should be updated. We currently rely on | ||
| `codecov.io <https://app.codecov.io/gh/legend-exp/legend-daq2lh5>`_ to keep track of | ||
| test coverage. A local report, which must be inspected before submitting pull | ||
| requests, can be generated by running: | ||
|
|
||
| .. code-block:: console | ||
| $ pytest --cov=lgdo | ||
| Documentation | ||
| ------------- | ||
|
|
||
| We adopt best practices in writing and maintaining *legend-daq2lh5*'s | ||
| documentation. When contributing to the project, make sure to implement the | ||
| following: | ||
|
|
||
| * Documentation should be exclusively available on the Project website | ||
| `legend-daq2lh5.readthedocs.io <https://legend-daq2lh5.readthedocs.io>`_. No READMEs, | ||
| GitHub/LEGEND wiki pages should be written. | ||
| * Pull request authors are required to provide sufficient documentation for | ||
| every proposed change or addition. | ||
| * Documentation for functions, classes, modules and packages should be provided | ||
| as `Docstrings <https://peps.python.org/pep-0257>`_ along with the respective | ||
| source code. Docstrings are automatically converted to HTML as part of the | ||
| *legend-daq2lh5* package API documentation. | ||
| * General guides, comprehensive tutorials or other high-level documentation | ||
| (e.g. referring to how separate parts of the code interact between each | ||
| other) must be provided as separate pages in ``docs/source/`` and linked in | ||
| the table of contents. | ||
| * Jupyter notebooks should be added to the main Git repository below | ||
| ``docs/source/notebooks``. | ||
| * Before submitting a pull request, contributors are required to build the | ||
| documentation locally and resolve and warnings or errors. | ||
|
|
||
| Writing documentation | ||
| ^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| We adopt the following guidelines for writing documentation: | ||
|
|
||
| * Documentation source files must formatted in reStructuredText (reST). A | ||
| reference format specification is available on the `Sphinx reST usage guide | ||
| <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_. | ||
| Usage of `Cross-referencing syntax | ||
| <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax>`_ | ||
| in general and `for Python objects | ||
| <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects>`_ | ||
| in particular is recommended. We also support cross-referencing external | ||
| documentation via `sphinx.ext.intersphinx | ||
| <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_, | ||
| when referring for example to :class:`pandas.DataFrame`. | ||
| * To document Python objects, we also adopt the `NumPy Docstring style | ||
| <https://numpydoc.readthedocs.io/en/latest/format.html>`_. Examples are | ||
| available `here | ||
| <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>`_. | ||
| * We support also the Markdown format through the `MyST-Parser | ||
| <https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html>`_. | ||
| * Jupyter notebooks placed below ``docs/source/notebooks`` are automatically | ||
| rendered to HTML pages by the `nbsphinx <https://nbsphinx.readthedocs.io>`_ | ||
| extension. | ||
|
|
||
| Building documentation | ||
| ^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| Scripts and tools to build documentation are located below ``docs/``. To build | ||
| documentation, ``sphinx`` and a couple of additional Python packages are | ||
| required. You can get all the needed dependencies by running: | ||
|
|
||
| .. code-block:: console | ||
| $ cd legend-daq2lh5 | ||
| $ pip install '.[docs]' | ||
| `Pandoc <https://pandoc.org/installing.html>`_ is also required to render | ||
| Jupyter notebooks. To build documentation, run the following commands: | ||
|
|
||
| .. code-block:: console | ||
| $ cd docs | ||
| $ make clean | ||
| $ make | ||
| Documentation can be then displayed by opening ``build/html/index.html`` with a | ||
| web browser. Documentation for the :mod:`legend-daq2lh5` website is built and deployed by | ||
| `Read the Docs <https://readthedocs.org/projects/legend-daq2lh5>`_. | ||
|
|
||
| Versioning | ||
| ---------- | ||
|
|
||
| Collaborators with push access to the GitHub repository that wish to release a | ||
| new project version must implement the following procedures: | ||
|
|
||
| * `Semantic versioning <https://semver.org>`_ is adopted. The version string | ||
| uses the ``MAJOR.MINOR.PATCH`` format. | ||
| * To release a new **minor** or **major version**, the following procedure | ||
| should be followed: | ||
|
|
||
| 1. A new branch with name ``releases/vMAJOR.MINOR`` (note the ``v``) containing | ||
| the code at the intended stage is created | ||
| 2. The commit is tagged with a descriptive message: ``git tag vMAJOR.MINOR.0 | ||
| -m 'short descriptive message here'`` (note the ``v``) | ||
| 3. Changes are pushed to the remote: | ||
|
|
||
| .. code-block:: console | ||
| $ git push origin releases/vMAJOR.MINOR | ||
| $ git push origin refs/tags/vMAJOR.MINOR.0 | ||
| * To release a new **patch version**, the following procedure should be followed: | ||
|
|
||
| 1. A commit with the patch is created on the relevant release branch | ||
| ``releases/vMAJOR.MINOR`` | ||
| 2. The commit is tagged: ``git tag vMAJOR.MINOR.PATCH`` (note the ``v``) | ||
| 3. Changes are pushed to the remote: | ||
|
|
||
| .. code-block:: console | ||
| $ git push origin releases/vMAJOR.MINOR | ||
| $ git push origin refs/tags/vMAJOR.MINOR.PATCH | ||
| * To upload the release to the `Python Package Index | ||
| <https://pypi.org/project/legend-daq2lh5>`_, a new release must be created through | ||
| `the GitHub interface <https://github.com/legend-exp/legend-daq2lh5/releases/new>`_, | ||
| associated to the just created tag. Usage of the "Generate release notes" | ||
| option is recommended. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters