This page provides procedures and guidelines for developing and contributing to the LSST EFD Client.
Scope of contributions#
LSST EFD Client is an open source package, meaning that you can contribute to the LSST EFD Client itself, or fork LSST EFD Client for your own purposes.
Since the LSST EFD Client is intended for internal use by Rubin Observatory, community contributions can only be accepted if they align with Rubin Observatory’s aims. For that reason, it’s a good idea to propose changes with a new GitHub issue before investing time in making a pull request.
The LSST EFD Client is developed by the Rubin SQuaRE team.
Setting up a local development environment#
To develop the LSST EFD Client, create a Python virtual environment with your method of choice and then clone or fork, and install:
git clone https://github.com/lsst-sqre/lsst-efd-client.git cd LSST EFD Client make init
This init step does three things:
Installs the LSST EFD Client in an editable mode with its “dev” extra that includes test and documentation dependencies.
Installs pre-commit and tox.
Installs the pre-commit hooks.
You must have Docker installed and configured so that your user can start Docker containers in order to run the test suite.
The pre-commit hooks, which are automatically installed by running the make init command on set up, ensure that files are valid and properly formatted. Some pre-commit hooks automatically reformat code:
Automatically sorts imports in Python modules.
Automatically formats Python code.
When these hooks fail, your Git commit will be aborted. To proceed, stage the new modifications and proceed with your Git commit.
To test the library, run tox, which tests the library the same way that the CI workflow does:
To see a listing of test environments, run:
To run a specific test or list of tests, you can add test file names (and any other pytest options) after
-- when executing the
py tox environment.
tox run -e py -- tests/test_lsst_efd_client.py
Documentation is built with Sphinx:
tox run -e docs
The build documentation is located in the
Updating the change log#
The LSST EFD Client uses scriv to maintain its change log.
When preparing a pull request, run scriv create.
This will create a change log fragment in
Edit that fragment, removing the sections that do not apply and adding entries fo this pull request.
You can pass the
--edit flag to scriv create to open the created fragment automatically in an editor.
Change log entries use the following sections:
Other changes (for minor, patch-level changes that are not bug fixes, such as logging formatting changes or updates to the documentation)
These entries will eventually be cut and pasted into the release description for the next release, so the Markdown for the change descriptions should be compatible with GitHub’s Markdown conventions for the release description. Specifically:
Each bullet point should be entirely on one line, even if it contains multiple sentences. This is an exception to the normal documentation convention of a newline after each sentence. Unfortunately, GitHub interprets those newlines as hard line breaks, so they would result in an ugly release description.
Avoid using too much complex markup, such as nested bullet lists, since the formatting in the GitHub release description may not be what you expect and manually editing it is tedious.
Document the Python API with numpydoc-formatted docstrings. See the LSST DM Docstring Style Guide.
Follow the LSST DM ReStructuredTextStyle Guide. In particular, ensure that prose is written one-sentence-per-line for better Git diffs.