Merge pull request #141 from funkelab/contributing

Add contributing docs

Author: cmalinmayor

.github/workflows/ci.yaml

@@ -13,16 +13,13 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Run pre-commit linting
         run: pipx run pre-commit run --all-files
 
   test:
     name: ${{ matrix.platform }} py${{ matrix.python-version }}
     runs-on: ${{ matrix.platform }}
-    defaults:
-      run:
-        shell: bash -l {0}
     strategy:
       fail-fast: false
       matrix:
@@ -33,23 +30,18 @@ jobs:
             python-version: "3.10"
 
     steps:
-      - uses: actions/checkout@v4
-
-      - uses: conda-incubator/setup-miniconda@v3
+      - uses: actions/checkout@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v6
         with:
           python-version: ${{ matrix.python-version }}
-          miniforge-version: latest
-          use-mamba: true
-          channels: conda-forge
-          channel-priority: true
+          enable-cache: true
 
-      - name: Install package and dependencies
-        run: |
-          mamba install -c gurobi -c funkelab ilpy
-          python -m pip install -e .[test]
+      - name: Install dependencies
+        run: uv sync
 
       - name: Test
-        run: pytest tests -v --color=yes --cov=motile --cov-report=xml
+        run: uv run pytest tests -v --color=yes --cov=motile --cov-report=xml
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5

.github/workflows/publish-docs.yaml

@@ -16,31 +16,22 @@ permissions:
 jobs:
   build:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        shell: bash -l {0}
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - uses: conda-incubator/setup-miniconda@v3
+      - uses: actions/checkout@v5
+      - name: Set up Python 3.11
+        uses: astral-sh/setup-uv@v6
         with:
-          python-version: "3.11"
-          miniforge-version: latest
-          use-mamba: true
-          channels: conda-forge
-          channel-priority: true
+          python-version: '3.11'
+          enable-cache: true
 
-      - name: Install package and dependencies
-        run: |
-          mamba install -c gurobi -c funkelab ilpy
-          python -m pip install -e .[docs]
+      - name: Install dependencies
+        run: uv sync
 
       - name: Build documentation
-        run: sphinx-build docs/source docs/build/html -W -b html
+        run: uv run sphinx-build docs/source docs/build/html -W -b html
 
       - name: Upload Pages Artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: docs/build/html
           retention-days: 90

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to `motile`
+
+:tada: Thank you for your interest in contributing to `motile`! :tada:
+
+`motile` is a research library. While it is stable and in use in multiple projects, the time
+available for the core developers to perform maintenance and feature requests is limited.
+The preferred form of communication for bugs and requests is GitHub 
+[Issues](https://github.com/funkelab/motile/issues/new) - if your issue does not get a 
+response in a reasonable time, feel free to ping @cmalinmayor and I will take at least a quick look.
+
+## New Costs and Constraints
+To keep this library manageable to maintain, we intentionally keep the number of `Variables`,
+`Costs`, and `Constraints` implemented here low, and highly encourage people with specific
+needs to extend the base classes to implement their own components within the `motile`
+framework.
+
+Examples of complex workflows can be found in experimental libraries that use `motile`, such as:
+- [`attrackt`](https://github.com/funkelab/attrackt)
+- [`mhat` (Multi Hypothesis Affinity Tracking)](https://github.com/funkelab/mhat)
+
+If you want to contribute a `Cost` or `Constraint` that is widely useful and should be part of
+the core library, please open an [Issue](https://github.com/funkelab/motile/issues/new) or PR and we will review it. If we can't
+commit to maintaining the code but think others can use it as inspiration, we might suggest
+contributing it to the [`motile_toolbox`](https://github.com/funkelab/motile_toolbox) instead.
+
+## Development Tools
+
+We use `uv` for dependency management, `ruff` for formatting and linting, and `mypy` for type checking.
+If set up correctly, the `pre-commit` configuration runs `ruff` and `mypy` before each commit.
+To set it up, navigate to the root directory of this repository and run:
+```bash
+uv run pre-commit install
+```
+
+To run the tests from the root directory:
+```bash
+uv run pytest
+```
+
+### Deployment
+
+To deploy a new version, first make sure to bump the version string in
+`motile/__init__.py`.  Then create an **annotated** tag, and push it to GitHub.
+This will trigger the `deploy.yaml` workflow to upload to PyPI
+
+```bash
+git tag -a vX.Y.Z -m vX.Y.Z
+git push upstream --follow-tags
+```
+
+### Building Documentation
+From root directory of the repository:
+```sh
+uv run make docs
+open docs/_build/html/index.html
+
+# or to start a live-reloading server
+uv run make docs-watch
+```

Makefile

@@ -6,8 +6,8 @@ install-dev:
 
 .PHONY: tests
 tests:
-	PY_MAJOR_VERSION=py`python -c 'import sys; print(sys.version_info[0])'` pytest -v --cov=motile --cov-config=.coveragerc tests
-	pre-commit run --all-files
+	uv run pytest -v --cov=motile --cov-config=.coveragerc tests
+	uv run pre-commit run --all-files
 
 .PHONY: publish
 publish:
@@ -21,5 +21,4 @@ docs:
 
 .PHONY: docs-watch
 docs-watch:
-	pip install sphinx-autobuild
 	sphinx-autobuild docs/source docs/_build/html --watch motile --watch docs/source --open-browser

README.md

@@ -11,62 +11,9 @@ Read all about it in the [documentation](https://funkelab.github.io/motile/).
 
 ## Installation
 
-Motile depends on [`ilpy`](https://github.com/funkelab/ilpy), which is currently only available via
-conda on the `funkelab` channel.  `ilpy` in turn requires
-gurobi which is only available via the `gurobi` channel.
-
-So, to create a new environment with motile:
-
-```bash
-conda create -n my_env -c conda-forge -c funkelab -c gurobi ilpy
-conda activate my_env
-pip install motile
-```
-
-or, to install into an existing environment:
-
 ```bash
-conda install -c conda-forge -c funkelab -c gurobi ilpy
 pip install motile
 ```
 
 ## Development
-
-```sh
-git clone https://github.com/funkelab/motile  # or your fork
-cd motile
-
-# currently required to build ilpy dependency wheel
-conda install scip
-
-pip install -e .[dev]
-```
-
-### Testing
-
-```sh
-pytest
-```
-
-### Deployment
-
-> note for developers
-
-To deploy a new version, first make sure to bump the version string in
-`motile/__init__.py`.  Then create an **annotated** tag, and push it to github.
-This will trigger the `deploy.yaml` workflow to upload to PyPI
-
-```bash
-git tag -a vX.Y.Z -m vX.Y.Z
-git push upstream --follow-tags
-```
-
-### Building Documentation
-
-```sh
-pip install -e .[docs]
-make docs && open docs/_build/html/index.html
-
-# or to start a live-reloading server
-make docs-watch
-```
+Check out CONTRIBUTING.md for more information on contributing to `motile`.

docs/source/install.rst

@@ -7,13 +7,11 @@ Installation
    :noindex:
 
 .. code-block:: bash
-
-  conda create -n motile -c conda-forge -c gurobi -c funkelab ilpy
-  conda activate motile
+   
   pip install motile
 
-This will install ``motile`` with all required dependencies, including binaries
-for two discrete optimizers:
+This will install ``motile`` with all required dependencies, including
+two discrete optimizers:
 
 1. The `Gurobi Optimizer <https://www.gurobi.com/>`_. This is a comercial
    solver, which requires a valid license. Academic licenses are provided for
@@ -22,16 +20,8 @@ for two discrete optimizers:
    to obtain one.
 
 2. The `SCIP Optimizer <https://www.scipopt.org/>`_, a free and open source
-   solver. If ``motile`` does not find a valid Gurobi license, it will fall
+   solver. If ``motile`` does not find a valid Gurobi license it will fall
    back to using SCIP.
 
-Do I have to use ``conda``?
----------------------------
-
-Kinda. ``motile`` uses `ilpy <https://github.com/funkelab/ilpy>`_ to solve the
-optimization problem. Conda packages for ``ilpy`` are available for all major
-platforms, linking against the conda packages for SCIP and Gurobi.
-
-It is possible to not use ``conda``: If you have SCIP or Gurobi installed
-otherwise, you can compile ``ilpy`` yourself from the PyPI repository (``pip
-install ilpy``).
+Developers can use `uv` for dependency management. See CONTRIBUTING.md for more
+information.

pyproject.toml

@@ -18,11 +18,27 @@ authors = [
     { name = 'Florian Jug', email = 'florian.jug@fht.org' },
 ]
 dynamic = ["version"]
-dependencies = ['networkx', 'ilpy>=0.4.0', 'numpy', 'structsvm']
+requires-python = ">=3.9"
+dependencies = [
+    'networkx',
+    'ilpy>=0.4.0',
+    'numpy',
+    'structsvm',
+]
 
-[project.optional-dependencies]
-dev = ["pre-commit", "pytest", "pytest-cov", "ruff", "twine", "build"]
-test = ["pytest", "pytest-cov"]
+[dependency-groups]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+dev = [
+    "pre-commit",
+    "ruff",
+    "twine",
+    "build",
+    {include-group="test"},
+    {include-group="docs"}
+]
 docs = [
     "ipykernel",
     "jupyter_sphinx",
@@ -33,6 +49,8 @@ docs = [
     "sphinx>6",
     "tomli",
     "motile_toolbox",
+    "plotly>=6.3",
+    "sphinx-autobuild",
 ]
 
 [project.urls]
@@ -94,4 +112,4 @@ strict = true             # feel free to relax this if it's annoying
 allow_untyped_defs = true # TODO: can eventually fill out typing and remove this
 # allow_untyped_calls = true    # TODO: can eventually fill out typing and remove this
 disallow_any_generics = false
-ignore_missing_imports = true
+ignore_missing_imports = true