Development¶

This comprehensive guide provides detailed instructions to help maintainers effectively develop, test, document, build, and release new versions of dimorphite_dl.

Setting up the Development Environment¶

dimorphite_dl utilizes pixi for managing environments and dependencies, streamlining the setup process. Follow these precise steps to configure your development environment:

Clone the repository: Begin by obtaining a local copy of the dimorphite_dl codebase:
```
git clone git@GitHub.com:durrantlab/dimorphite_dl.git
cd dimorphite_dl
```
2. Install dependencies: Install all necessary dependencies by running:
```
pixi install
```
3. Activate the development environment: To enter the isolated virtual environment configured specifically for dimorphite_dl development, execute:
```
pixi shell
```

You are now fully prepared and equipped to develop dimorphite_dl.

Code Formatting and Style Guide¶

Maintaining consistent style and formatting across the codebase is crucial for readability and maintainability. dimorphite_dl employs automated formatting tools configured to enforce standardized style guidelines. Execute the following command to apply formatting automatically:

pixi run format

This command sequentially runs black for Python formatting, isort for managing imports, and markdownlint-cli2 to enforce markdown formatting standards, ensuring your contributions align with project conventions.

Documentation¶

dimorphite_dl's documentation is built using MkDocs, allowing easy creation and maintenance of high-quality documentation. To locally preview documentation changes, serve the documentation by running:

pixi run -e docs serve-docs

After execution, open your web browser and visit http://127.0.0.1:8000/ to review changes in real-time.

Testing¶

Writing and maintaining tests is essential for ensuring code correctness, reliability, and stability. Execute dimorphite_dl's tests with:

pixi run -e dev tests

Additionally, you can evaluate test coverage to identify untested areas and improve overall reliability by running:

pixi run -e dev coverage

Review the generated coverage reports to address any gaps in testing.

Bumping Version¶

Releasing a new version of dimorphite_dl requires updating version information, documenting changes, and creating a corresponding release tag. Follow these steps precisely to ensure consistency and traceability:

Update the changelog: Document all notable changes since the previous release in the CHANGELOG.md file. Follow a consistent and clear format to help users understand what has changed.
Commit the changes: Stage and commit the version bump and changelog update using a clear and standardized message, for example:

git add .
git commit -m "bump: v1.2.5"

Tag the commit: Create a version tag that follows the v<version> format:

git tag v1.2.5
git push origin main --tags

Create a GitHub release: Navigate to the GitHub Releases page and draft a new release:
Tag version: v1.2.5
Release title: v1.2.5
Description: Copy the relevant changelog section or summarize the key changes.

Attach the built package files from the dist/ directory, if desired.

Building the Package¶

Prepare dimorphite_dl for publishing or distribution by building the package. Execute:

pixi run build

Upon completion, inspect the dist directory for the generated distribution files, which are ready for publication.

Publishing to PyPI¶

Once the version number is updated and the package is built, it can be published to PyPI. Execute:

pixi run publish

For preliminary testing or release candidates, it is highly recommended to publish to TestPyPI first. Execute:

pixi run publish-test

Publishing to TestPyPI allows you to validate packaging correctness and installation processes without affecting production users.

Maintenance Best Practices¶

To maintain high quality and reliability of dimorphite_dl, adhere to the following best practices:

Regularly synchronize your local repository with the main branch to incorporate the latest updates:
```
git pull origin main
```
- Frequently review and address open issues and pull requests on GitHub. - Clearly document changes in commit messages, issue descriptions, and pull requests. - Routinely verify dependencies and update them as necessary to maintain compatibility and security.

Adhering to these guidelines ensures a robust, stable, and continuously improving dimorphite_dl project.

This expanded documentation guide covers the entire workflow comprehensively, providing clarity and precision for effective dimorphite_dl project maintenance.