Development guide¶
This page provides procedures and guidelines for developing and contributing to Times Square.
Scope of contributions¶
Times Square is an open source package, meaning that you can contribute to Times Square itself, or fork Times Square for your own purposes.
Since Times Square 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.
Times Square is developed by the Rubin Observatory SQuaRE team.
Setting up a local development environment¶
Times Square is a Python project that should be developed within a virtual environment.
If you already have a Python virtual environment set up in your shell, you can use the make init command to install Times Square and its development dependencies into it. This complete procedure shows how to use uv to create a virtual environment and install Times Square into it:
git clone https://github.com/lsst-sqre/times-square.git
cd times-square
uv venv
source .venv/bin/activate
make init
Pre-commit¶
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:
The ruff
hook automatically fixes some common Python issues and sorts Python imports.
When these hooks fail, your Git commit will be aborted. To proceed, stage the new modifications and proceed with your Git commit.
Running tests¶
To test all components of Times Square, run tox, which tests the library the same way that the GitHub Actions CI workflow does:
tox run
To see a listing of specific tox sessions, run:
tox list
Times Square requires Docker to run its tests.
Database migrations¶
Times Square uses Alembic for database migrations.
If your work involves changing the database schema (in /src/timessquare/dbschema
) you will need to prepare an Alembic migration in the same PR.
To create the migration, you will need to run a local postgres database for Alembic to compare the current schema to the new schema:
With your existing codebase (before your changes; switch branches or stash changes if necessary), start up the database:
docker-compose -f docker-compose.yaml up
Initialize the database:
tox run -e cli -- init
Apply code changes to the database schema in
/src/timessquare/dbschema
.Generate the Alembic migration:
tox run -e alembic -- revision --autogenerate -m "Your migration message."
Review the migration in
alembic/versions/
and make any necessary changes. In particular, enums require special handling. See the Safir documentation for more information.Apply the migration to the running database:
tox run -e cli -- update-db-schema --alembic-config-path alembic.ini
Shut down the database:
docker-compose -f docker-compose.yaml down
For more general information about preparing Alembic migrations, see the Safir documentation.
Note that in Times Square the docker-compose.yaml
is hosted in the root of the repository rather than in the alembic
directory.
Building documentation¶
Documentation is built with Sphinx:
tox run -e docs
The build documentation is located in the docs/_build/html
directory.
To check the documentation for broken links, run:
tox run -e docs-linkcheck
Updating the change log¶
Times Square uses scriv to maintain its change log.
When preparing a pull request, run
scriv create
This will create a change log fragment in changelog.d
.
Edit that fragment, removing the sections that do not apply and adding entries for your pull request.
Change log entries use the following sections:
Backward-incompatible changes
New features
Bug fixes
Other changes (for minor, patch-level changes that are not bug fixes, such as logging formatting changes or updates to the documentation)
Do not include a change log entry solely for updating pinned dependencies, without any visible change to Times Square’s behavior. Every release is implicitly assumed to update all pinned dependencies.
These entries will eventually be cut and pasted into the release description for the next release, so the Markdown for the change descriptions must 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.
Style guide¶
Code¶
Documentation¶
Follow the LSST DM User Documentation Style Guide, which is primarily based on the Google Developer Style Guide.
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.