Contributing

Development setup

1. Install uv
2. Clone the repository:

git clone https://github.com/opencitations/time-agnostic-library
cd time-agnostic-library

3. Install all dependencies:

uv sync --dev

4. Build the package (output: dist/):

uv build

Running the tests

Tests require Docker to be running.

1. Start the test database:

# On Linux/macOS
chmod +x ./tests/start-test-database.sh
./tests/start-test-database.sh

# On Windows (PowerShell)
./tests/start-test-database.ps1

2. Run the tests with coverage:

uv run coverage run --rcfile=tests/coverage/.coveragerc
uv run coverage report

3. Generate an HTML coverage report:

uv run coverage html -d htmlcov

4. Stop the test database:

# On Linux/macOS
chmod +x ./tests/stop-test-database.sh
./tests/stop-test-database.sh

# On Windows (PowerShell)
./tests/stop-test-database.ps1

Building the documentation

cd docs
npm install
npm run dev      # Local preview
npm run build    # Production build

Release process

The project uses semantic-release for automated releases.

Commit message format

Commit messages follow the Conventional Commits specification:

• fix: ... triggers a PATCH version bump
• feat: ... triggers a MINOR version bump
• feat!: ... / fix!: ... / refactor!: ... triggers a MAJOR version bump

Triggering a release

Include [release] in the commit message:

git commit -m "feat: add new feature [release]"
git push origin main

The release workflow will:

1. Run tests via GitHub Actions
2. Update CHANGELOG.md and pyproject.toml
3. Create a GitHub release with release notes
4. Publish the package to PyPI

How to contribute

1. Fork the repository
2. Create a new branch for your feature or bugfix
3. Make your changes
4. Submit a pull request