Contributing

Contributions are welcome — bug reports, feature requests, documentation improvements, and pull requests.

Reporting bugs

Please open an issue on GitHub with:

The version of welltest-pta (python -c "import welltest_pta; print(welltest_pta.__version__)").
The Python version and OS.
A minimal reproducible example — ideally something that runs on the synthetic data generator so anybody can reproduce locally.
The exact traceback (if any).

Setting up a development environment

git clone https://github.com/geoharkat/welltest-pta.git
cd welltest-pta
python -m venv .venv
source .venv/bin/activate              # Linux/macOS
# .venv\\Scripts\\Activate.ps1          # Windows PowerShell
pip install -e ".[dev,docs,excel]"

Running the test suite

pytest -v                              # all tests
pytest -k bourdet                      # tests matching a pattern
pytest --cov=welltest_pta --cov-report=html
open htmlcov/index.html                # macOS — coverage report

Targets:

All tests must pass on Python 3.9 → 3.12.
Coverage should not decrease.
New features need at least one test.

Linting and type checking

We use ruff for linting and mypy for type checking:

ruff check src/ tests/ examples/
ruff format --check src/ tests/
mypy src/welltest_pta

CI will reject code that fails ruff check or ruff format --check.

Building the documentation

pip install -e ".[docs]"
sphinx-build -b html docs/source docs/build/html
python -m http.server -d docs/build/html 8000

Then open http://localhost:8000.

Pull request workflow

Fork the repository and create a branch off main:
```
git checkout -b feature/my-thing
```
Make your changes. Keep commits small and well-scoped.
Add or update tests. Documentation updates are appreciated for any user-facing change.

Run the full validation suite locally:

ruff check src/ tests/ examples/
ruff format --check src/ tests/
mypy src/welltest_pta
pytest -v

Push and open a pull request against main. The CI workflow will run automatically.

Release process (maintainers)

Bump __version__ in src/welltest_pta/__version__.py.
Add a section to CHANGELOG.md under [X.Y.Z] — YYYY-MM-DD.

Commit and tag:

git commit -am "Release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags

The release.yml workflow takes over: builds wheel + sdist, publishes to PyPI via OIDC trusted publishing, and creates a GitHub release with the changelog section as release notes.

Coding style

Docstrings use NumPy style — see existing modules for examples.
Equations in docstrings use raw-string form so backslashes are preserved, e.g. r"\\Delta p = ...".
Public functions get type hints.
Avoid abbreviations except where the petroleum domain demands them (DD, BU, IARF, MDH, FVF, etc.).
Field oilfield units throughout (psi, ft, cp, RB/STB, mD, …) unless explicitly stated.

Code of conduct

Be kind, professional, and assume good intent. Personal attacks, harassment, or off-topic political discussion are not welcome.