From 25851063ec2be74266b7080258a815f1fe2f101e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Sat, 25 Oct 2025 22:43:44 +0200 Subject: [PATCH 1/8] Draft a guide for the release process --- docs/development/index.md | 9 ++++++ docs/development/release.md | 63 +++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + 3 files changed, 73 insertions(+) create mode 100644 docs/development/index.md create mode 100644 docs/development/release.md diff --git a/docs/development/index.md b/docs/development/index.md new file mode 100644 index 0000000..b31ceb7 --- /dev/null +++ b/docs/development/index.md @@ -0,0 +1,9 @@ +# Development + +Resources for and about the development of docstub. + +:::{toctree} +:maxdepth: 1 + +release +::: diff --git a/docs/development/release.md b/docs/development/release.md new file mode 100644 index 0000000..1f22615 --- /dev/null +++ b/docs/development/release.md @@ -0,0 +1,63 @@ +# Release process + +This section documents the steps to make a release of docstub. +Depending on the release type not all steps may be mandatory – use appropriate judgement. + + +## Create release notes + +Generate a [read-only GitHub token](https://github.com/settings/personal-access-tokens), install [changelist](https://github.com/scientific-python/changelist), and generate a first draft of the release notes with it. + +```shell +pip install changelist + +RELEASE_TAG= +PREV_TAG= +export GH_TOKEN=... + +changelist scientific-python/docstub \ + --version "${RELEASE_TAG}" \ + --out "doc/release_notes/v${RELEASE_TAG}.md" \ + "${PREV_TAG}" main +``` + +`RELEASE_TAG` is the tag of the current release (for example `v1.1.0`), `PREV_TAG` is the tag of the previous release (for example `v1.0.0`). +So changelist will generate notes based on the changes between `PREV_TAG..main`. + +Review and update `doc/release_notes/v${RELEASE_TAG}.md`. +Don't forget to add the new document to `doc/release_notes/index.md`. + +Create a pull request with the new release notes. +If desired, include this pull request in the release notes, too. + + +## Create a new tag + +Once the pull request with the release notes is merged, tag the resulting commit with the desired version tag. +This should be a signed tag. + +```shell +git tag --sign "v${RELEASE_TAG}" +``` + +Include the release notes in the tag's message in the same formatting style as other release tags. + +Review and then push the tag: + +```shell +git push origin "v${RELEASE_TAG}" +``` + + +## Create a new "version" on Read the Docs + + +## Trigger release workflow on GitHub + +Trigger [docstub's release workflow on GitHub](https://github.com/scientific-python/docstub/actions/workflows/cd.yml). +As a security measure, this workflow needs to be approved by one eligible maintainer. +If successful, the workflow will build the package and push it to PyPI. + + +## Format and publish GitHub release + diff --git a/docs/index.md b/docs/index.md index 19fb24e..16d81c6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,6 +22,7 @@ It does so by supporting widely used readable conventions such as `array of dtyp installation introduction +development/index ::: :::{toctree} From ca0d611578bef04cdbebf46bf9d8277490a4f3ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Sun, 26 Oct 2025 14:28:41 +0100 Subject: [PATCH 2/8] Update project URLs in pyproject.toml --- pyproject.toml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 34bb588..8569630 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,7 +42,8 @@ dependencies = [ ] [project.urls] -Homepage = "https://github.com/lagru/docstub" +Source = "https://github.com/lagru/docstub" +Documentation = "https://docstub.readthedocs.io" [project.scripts] docstub = "docstub.__main__:cli" From ae0bbd57602303e93e679512a32dd765e2775c0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Sun, 26 Oct 2025 14:29:07 +0100 Subject: [PATCH 3/8] Draft contribution guide --- docs/development/contributing.md | 67 ++++++++++++++++++++++++++++++++ docs/development/index.md | 1 + 2 files changed, 68 insertions(+) create mode 100644 docs/development/contributing.md diff --git a/docs/development/contributing.md b/docs/development/contributing.md new file mode 100644 index 0000000..938c93e --- /dev/null +++ b/docs/development/contributing.md @@ -0,0 +1,67 @@ +# Contributing + +## Design goals + +- Docsub is not a type checker. +- Type annotation patterns that are too complex to express reasonably in docstrings, won't be supported. + For these cases, docstub encourages fallback mechanisms (like inline annotations, or creating a stub file manually). + + +## Bug reports, feature requests and feedback + +Head over to [docstub's issue tracker](https://github.com/scientific-python/docstub/issues) and feel very welcome to open an issue! + + +## Development workflow + +This section assumes familiarity with Python development. +For a more general introduction you can check out [Scientific Python's Intro to development](https://learn.scientific-python.org/development/tutorials/dev-environment/). + + +### Setup a development environment + +Create a [fork of docstub](https://github.com/scientific-python/docstub/fork) and clone your fork. +The following sections assume that you are running a shell inside that cloned project folder (`docstub/`). + +```shell +pip install --group dev --editable . +pre-commit install +``` + + +### Run tests + +Run test suite and doctests: + +```shell +python -m pytest +``` + +Check stub files for docstub: + +```shell +python -m mypy.stubtest \ + --mypy-config-file "pyproject.toml" \ + --allowlist "stubtest_allow.txt" \ + docstub +``` + +Type check test suite: + +```shell +python -m mypy "tests/" +python -m basedpyright "tests/" +``` + +Before committing you can also perform all linting checks explicitly with + +```shell +pre-commit run --all +``` + + +### Build the documentation + +```shell +python -m sphinx --fresh-env --nitpicky --fail-on-warning "docs/" "docs/build/" +``` diff --git a/docs/development/index.md b/docs/development/index.md index b31ceb7..b288adb 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -5,5 +5,6 @@ Resources for and about the development of docstub. :::{toctree} :maxdepth: 1 +contributing release ::: From e26537b7f62d43a48081647ab309de7a57e6d62e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Thu, 8 Jan 2026 23:18:44 +0100 Subject: [PATCH 4/8] Complete release guide --- docs/development/release.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/development/release.md b/docs/development/release.md index 1f22615..e7d8c98 100644 --- a/docs/development/release.md +++ b/docs/development/release.md @@ -11,8 +11,8 @@ Generate a [read-only GitHub token](https://github.com/settings/personal-access- ```shell pip install changelist -RELEASE_TAG= -PREV_TAG= +RELEASE_TAG=... +PREV_TAG=... export GH_TOKEN=... changelist scientific-python/docstub \ @@ -21,8 +21,10 @@ changelist scientific-python/docstub \ "${PREV_TAG}" main ``` -`RELEASE_TAG` is the tag of the current release (for example `v1.1.0`), `PREV_TAG` is the tag of the previous release (for example `v1.0.0`). -So changelist will generate notes based on the changes between `PREV_TAG..main`. +- `RELEASE_TAG` is the tag of the current release (for example `v1.1.0`) +- `PREV_TAG` is the tag of the previous release (for example `v1.0.0`). + +So changelist will generate notes based on the changes between `${PREV_TAG}..main`. Review and update `doc/release_notes/v${RELEASE_TAG}.md`. Don't forget to add the new document to `doc/release_notes/index.md`. @@ -51,6 +53,10 @@ git push origin "v${RELEASE_TAG}" ## Create a new "version" on Read the Docs +Login to https://app.readthedocs.org/projects/docstub. + +Create a [new version](https://app.readthedocs.org/dashboard/docstub/version/create/) for the tag corresponding to the new release. + ## Trigger release workflow on GitHub @@ -61,3 +67,7 @@ If successful, the workflow will build the package and push it to PyPI. ## Format and publish GitHub release +[Create a new release draft](https://github.com/scientific-python/docstub/releases/new) and copy the content of `doc/release_notes/v${RELEASE_TAG}.md` into it. +(Remove the duplicate level 1 headline in the first line.) + +Review and publish. From a63b9ef2a1ab0b72f80a8cfc5a02d763af27cc4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Thu, 8 Jan 2026 23:19:16 +0100 Subject: [PATCH 5/8] Tweak contribution guide --- docs/development/contributing.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/development/contributing.md b/docs/development/contributing.md index 938c93e..11ecb57 100644 --- a/docs/development/contributing.md +++ b/docs/development/contributing.md @@ -1,12 +1,5 @@ # Contributing -## Design goals - -- Docsub is not a type checker. -- Type annotation patterns that are too complex to express reasonably in docstrings, won't be supported. - For these cases, docstub encourages fallback mechanisms (like inline annotations, or creating a stub file manually). - - ## Bug reports, feature requests and feedback Head over to [docstub's issue tracker](https://github.com/scientific-python/docstub/issues) and feel very welcome to open an issue! @@ -65,3 +58,13 @@ pre-commit run --all ```shell python -m sphinx --fresh-env --nitpicky --fail-on-warning "docs/" "docs/build/" ``` + + +## Design goals + +- Docstub is not a type checker. +- Docstub is not a linter. +- Docstub aims for readable type descriptions in docstrings. + It should not introduce more complexity in docstrings than if [Python-native annotations](https://typing.python.org/en/latest/spec/glossary.html#term-annotation-expression) were used. +- Docstub encourages fallback mechanisms like inline annotations, or creating a stub file manually. + This helps with cases that would have a poor readability in docstrings, would be very complex, or are not supported. From fb2522c0e5fa44e4547d32a488880eb976a2bf0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 9 Jan 2026 15:29:49 +0100 Subject: [PATCH 6/8] Add design & style guide --- docs/development/design.md | 16 ++++++++++++++++ docs/development/index.md | 1 + 2 files changed, 17 insertions(+) create mode 100644 docs/development/design.md diff --git a/docs/development/design.md b/docs/development/design.md new file mode 100644 index 0000000..c2733b2 --- /dev/null +++ b/docs/development/design.md @@ -0,0 +1,16 @@ +# Design and style guide + +## Goals + +- Docstub facilitates gradual and easy adoption. +- Docstub aims for readable type descriptions in docstrings. + Extended doctype syntax should improve readability and work with existing conventions. +- Docstub encourages fallback mechanisms like inline annotations, or creating a stub file manually. + This helps with cases that would have a poor readability in docstrings, would be very complex, or are not supported. +- Docstub is not a type checker. +- Docstub is not a linter. + +The development is, in part, motivated by an effort to add type annotations to the [scikit-image project](https://scikit-image.org). +This may inform some short-term priorities and the roadmap. + +That said, docstub is a project for the community and welcomes ideas, feedback, and contributions in any form! diff --git a/docs/development/index.md b/docs/development/index.md index b288adb..6663beb 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -6,5 +6,6 @@ Resources for and about the development of docstub. :maxdepth: 1 contributing +design release ::: From 49801084384d807cc269eb70b0c45d7e0cbabcf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 9 Jan 2026 16:02:44 +0100 Subject: [PATCH 7/8] Overwrite org CONTRIBUTION guide See https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors --- .github/CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..66f26ff --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,3 @@ +You can find docstub's [contribution guide in our HTML docs](https://docstub.readthedocs.io/latest/development/contributing.html). + +Or find its source in this repository at [docs/development/contributing.md](/docs/development/contributing.md) From d8bbc89bd3c59f27b50e6674ba5af94c82b0788c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lars=20Gr=C3=BCter?= Date: Fri, 9 Jan 2026 16:03:21 +0100 Subject: [PATCH 8/8] Tweak contribution and installation guides --- docs/development/contributing.md | 22 ++++++++++------------ docs/installation.md | 8 ++++++-- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/development/contributing.md b/docs/development/contributing.md index 11ecb57..97b6717 100644 --- a/docs/development/contributing.md +++ b/docs/development/contributing.md @@ -1,8 +1,16 @@ # Contributing -## Bug reports, feature requests and feedback +Thanks for trying out docstub and being interested in contributing! +We'd greatly appreciate feedback and bug reports, as well as pointers to where the documentation is confusing and unclear. -Head over to [docstub's issue tracker](https://github.com/scientific-python/docstub/issues) and feel very welcome to open an issue! +Our project follows [Scientific Python's Code of Conduct](https://scientific-python.org/code_of_conduct/). + + +## Reaching out + +For bug reports, feature requests and feedback, head over to [docstub's issue tracker](https://github.com/scientific-python/docstub/issues) and feel very welcome to open an issue! 🚀 + +Before creating a feature request it might be useful to reference our [design guide](design.md), specifically our [goals](design.md#goals). ## Development workflow @@ -58,13 +66,3 @@ pre-commit run --all ```shell python -m sphinx --fresh-env --nitpicky --fail-on-warning "docs/" "docs/build/" ``` - - -## Design goals - -- Docstub is not a type checker. -- Docstub is not a linter. -- Docstub aims for readable type descriptions in docstrings. - It should not introduce more complexity in docstrings than if [Python-native annotations](https://typing.python.org/en/latest/spec/glossary.html#term-annotation-expression) were used. -- Docstub encourages fallback mechanisms like inline annotations, or creating a stub file manually. - This helps with cases that would have a poor readability in docstrings, would be very complex, or are not supported. diff --git a/docs/installation.md b/docs/installation.md index 294b943..f72c02e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -12,8 +12,7 @@ You can use an isolated environment for docstub. So things like `pipx run docstub` or `uv tool run docstub` will work, too. -## Development version - +## Unreleased version In case you want to check out an unreleased version you can install the latest version directly from the repository with: ```shell @@ -21,3 +20,8 @@ pip install 'docstub @ git+https://github.com/scientific-python/docstub' ``` You can append `@COMMIT_SHA` to the repository URL above to intall a specific version other that the `main` branch. + +:::{tip} +If you are want to set up a development environment instead, checkout the [Contribution guide](development/contributing.md). +::: +