From 25851063ec2be74266b7080258a815f1fe2f101e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20Gr=C3=BCter?= <lagru@mailbox.org>
Date: Sat, 25 Oct 2025 22:43:44 +0200
Subject: [PATCH 1/3] 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?= <lagru@mailbox.org>
Date: Sun, 26 Oct 2025 14:28:41 +0100
Subject: [PATCH 2/3] 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?= <lagru@mailbox.org>
Date: Sun, 26 Oct 2025 14:29:07 +0100
Subject: [PATCH 3/3] 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
 :::