Merge branch 'main' into use-stapi-pydantic-in-stapi-fastapi

j-tr · web-flow · commit 379c8a42c433 · 2025-04-02T09:29:50.000+01:00
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,13 @@
+## What I'm changing
+
+- <!-- a list of changes, including any issues this might close or reference -->
+
+## How I did it
+
+- <!-- more detail on decisions and choices -->
+
+## Checklist
+
+- [ ] Tests pass: `uv run pytest`
+- [ ] Checks pass: `uv run pre-commit --all-files`
+- [ ] CHANGELOG is updated (if necessary)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,67 @@
+# Contributing
+
+First, thanks for contributing to **pystapi**!
+The [README](./README.md#development) as instructions on setting up your development environment, which is a great place to start.
+
+## Repository organization
+
+**pystapi** is a "monorepo", meaning that it contains several sub-projects.
+Each project has it's own `pyproject.toml` file, README, CHANGELOG, tests, and more.
+Development dependencies should be specified at the top-level `pyproject.toml` file, as tests are intended to be run for the entire repository at once.
+
+## Branches
+
+We have a single primary development branch, **main**.
+Releases are cut from this branch by tags.
+Tags are named to identify which project they are releasing, e.g. a **stapi-pydantic** tag might look like `stapi-pydantic/v0.1.2`.
+If necessary, long-lived release branches are used to manage non-breaking changes and fixes, e.g. a `stapi-pydantic/v0.1` branch to handle any bugfixes that need to be backported to the v0.1 lineage of the project after **main** has incorporated breaking changes.
+
+## Testing
+
+We use [pytest](https://docs.pytest.org).
+Tests should be written in the "pytest style", i.e. free functions.
+
+Good:
+
+```python
+def test_foo() -> None:
+    assert 1 == 1
+```
+
+Bad:
+
+```python
+class FooTest(unittest.TestCase):
+    def test_foo(self) -> None:
+        assert 1 == 1
+```
+
+## Static typing
+
+We use [mypy](https://mypy-lang.org/) for static typing.
+When possible, projects work in `strict` mode, meaning that type checking is strongly enforced.
+Some projects are not quite ready for `strict` mode, but we want to get them there.
+
+## Lints and checks
+
+We use [pre-commit](https://pre-commit.com/).
+If you want to run checks on every commit:
+
+```shell
+uv run pre-commit install
+```
+
+If you ever need to disable **pre-commit** when committing use `--no-verify`:
+
+```shell
+git commit --no-verify
+```
+
+## Submitting changes
+
+Open a [pull request](https://github.com/stapi-spec/pystapi/pulls) with your changes, and fill out the provided template.
+It's not required, but it's helpful if you name your pull request in the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) style, as the pull request titles are the eventual commit title for your changes (we use squash-and-merge).
+A **pystapi** maintainer will review your PR and request any changes.
+Once approved, if you have the permissions you can merge your PR ... if you don't, a maintainer will.
+
+If your PR is not ready for review, but you'd like some feedback on it anyways, open it as a draft.
diff --git a/README.md b/README.md
@@ -1,10 +1,52 @@
 # pystapi
 
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/stapi-spec/pystapi/ci.yaml?style=for-the-badge)](https://github.com/stapi-spec/pystapi/actions/workflows/ci.yaml)
+
 Monorepo for Python Satellite Tasking API (STAPI) Specification packages.
+For more, see our [docs](https://stapi-spec.github.io/pystapi/).
 
-## Packages
+## Development
+
+Get [uv](https://docs.astral.sh/uv/), then:
+
+```shell
+git clone git@github.com:stapi-spec/pystapi.git
+cd pystapi
+uv sync
+```
+
+Test:
+
+```shell
+uv run pytest
+```
+
+Check formatting and other lints:
+
+```shell
+uv run pre-commit --all-files
+```
 
-This diagram is aspirational while we build out things during the 2025 STAPI sprint in Lisbon.
+If you don't want to type `uv run` all the time:
+
+```shell
+source .venv/bin/activate
+```
+
+See our [contribution guidelines](./CONTRIBUTING.md) for information on contributing any changes, fixes, or features.
+
+### stapi-fastapi server
+
+A minimal test implementation is provided in [stapi-fastapi/tests/application.py](stapi-fastapi/tests/application.py).
+Run it like so:
+
+```commandline
+uv run fastapi dev stapi-fastapi/tests/application.py
+```
+
+The app should be accessible at `http://localhost:8000`.
+
+## Packages
 
 ```mermaid
 graph
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1 @@
+# pystapi
diff --git a/pyproject.toml b/pyproject.toml
@@ -70,8 +70,9 @@ module = "pygeofilter.parsers.*"
 ignore_missing_imports = true
 
 [tool.pymarkdown]
-plugins.md013.line_length = 120
+plugins.md013.enabled = false  # @gadomski likes to do one-line-per-sentence in markdown
 plugins.md024.enabled = false  # duplicate headers in changelog
+plugins.md041.enabled = false  # github templates don't start with an h1
 
 [tool.coverage.report]
 show_missing = true
diff --git a/stapi-fastapi/README.md b/stapi-fastapi/README.md
@@ -1,7 +1,7 @@
 # STAPI FastAPI - Sensor Tasking API with FastAPI
 
-WARNING: The whole [STAPI spec] is very much a work in progress, so things are
-guaranteed to be not correct.
+> [!WARNING]
+> The whole [STAPI spec] is very much a work in progress, so things are guaranteed to be not correct.
 
 ## Usage
 
@@ -11,8 +11,9 @@ STAPI FastAPI provides an `fastapi.APIRouter` which must be included in
 ### Pagination
 
 4 endpoints currently offer pagination:
-`GET`: `'/orders`, `/products`, `/orders/{order_id}/statuses`
-`POST`: `/opportunities`.
+
+- `GET`: `'/orders`, `/products`, `/orders/{order_id}/statuses`
+- `POST`: `/opportunities`.
 
 Pagination is token based and follows recommendations in the [STAC API pagination].
 Limit and token are passed in as query params for `GET` endpoints, and via the body as
@@ -28,50 +29,10 @@ returned indicates there are no further records available.
 
 ADRs can be found in in the [adrs](./adrs/README.md) directory.
 
-## Development
-
-It's 2024 and we still need to pick our poison for a 2024 dependency management
-solution. This project picks [poetry] for now.
-
-### Dev Setup
-
-Setup is managed with `poetry` and `pre-commit`. It's recommended to install
-the project into a virtual environment. Bootstrapping a development environment
-could look something like this:
-
-```commandline
-python -m venv .venv
-source .venv/bin/activate
-pip install poetry  # if not already installed to the system
-poetry install --with dev
-pre-commit install
-```
-
-### Test Suite
-
-A `pytest` based test suite is provided, and can be run simply using the
-command `pytest`.
-
-### Dev Server
-
-This project cannot be run on its own because it does not have any backend
-implementations. However, a minimal test implementation is provided in
-[`./tests/application.py`](./tests/application.py). It can be run with
-`uvicorn` as a way to interact with the API and to view the OpenAPI
-documentation. Run it like so from the project root:
-
-```commandline
-uvicorn application:app --app-dir ./tests --reload
-```
-
-With the `uvicorn` defaults the app should be accessible at
-`http://localhost:8000`.
-
 ### Implementing a backend
 
 - The test suite assumes the backend can be instantiated without any parameters
   required by the constructor.
 
 [STAPI spec]: https://github.com/stapi-spec/stapi-spec
-[poetry]: https://python-poetry.org/
 [STAC API pagination]: https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/item-search/examples.md#paging-examples
