Contributing

Contributions of all kinds are welcome: bug reports, feature requests, documentation improvements, and code contributions. All work is coordinated through GitHub Issues.

Reporting a bug

Open an issue on GitHub and include:

  • A minimal, self-contained code example that reproduces the problem
  • The full version string: print(ammonyte.__version__)
  • The error message or incorrect output you observe
  • Your Python version and operating system

The more specific the report, the faster it can be resolved.

Suggesting a feature

Open an issue with the label enhancement and describe:

  • What you would like to see
  • Why it would be useful
  • If possible, a sketch of how it might work

For non-trivial features, consider prototyping the idea in a notebook first, showing the proposed API and a working example.

Contributing code

1. Fork and clone

Fork the repository on GitHub, then clone your fork locally and add the upstream remote:

git clone https://github.com/your-username/Ammonyte.git
cd Ammonyte
git remote add upstream https://github.com/LinkedEarth/Ammonyte.git

2. Set up the development environment

conda env create -f .binder/environment.yml
conda activate ammonyte_env
pip install -e .

3. Create a branch

Always branch from an up-to-date main:

git pull upstream main --ff-only
git checkout -b my-feature

Use a descriptive branch name that reflects the change (e.g. fix/kstest-edge-case, feature/geoseries).

4. Make your changes

  • Add or update tests for any new or changed behaviour
  • Update docstrings to reflect any API changes
  • Keep changes focused (one feature or fix per branch)

5. Run the tests

pytest ammonyte/tests/

All tests must pass before submitting a pull request.

6. Commit your changes

Write a short, descriptive commit message (under 80 characters). If the commit closes a GitHub issue, reference it in the body:

Add GeoSeries class with lat/lon/elevation metadata

Closes #23
git add path/to/changed_file.py
git commit -m "your message"
git push origin my-feature

7. Open a pull request

Open a pull request against the main branch of LinkedEarth/Ammonyte. In the PR description:

  • Summarise what changed and why
  • Reference the related issue (e.g. Closes #23)
  • List any decisions or trade-offs worth noting

Before submitting, verify that:

If the upstream main has moved since you branched, update your branch before merging:

git merge upstream/main

8. After the PR is merged

Delete the feature branch locally and on your fork:

git branch -d my-feature
git push origin --delete my-feature

Code style

  • Follow the existing conventions in the codebase
  • Use descriptive variable names
  • Docstrings must follow NumPy style and include a Parameters, Returns, and Examples section

A minimal docstring example:

def my_function(x, threshold=0.05):
    """
    One-line summary of what the function does.

    Parameters
    ----------
    x : array-like
        Input data.
    threshold : float, optional
        Significance threshold. Default is 0.05.

    Returns
    -------
    result : float
        Description of the return value.

    Examples
    --------
    >>> import ammonyte as amt
    >>> result = my_function([1, 2, 3])
    """

Testing conventions

  • Place tests in ammonyte/tests/
  • Name test files test_<module>.py (e.g. test_core_series.py)
  • Name test functions test_<method> (e.g. test_kstest_returns_transitions)
  • Use the datasets bundled with the package where possible
  • Keep tests minimal and focused — each test should verify one behaviour