Add contribution & release guide

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/"
+```

docs/development/index.md

@@ -0,0 +1,10 @@
+# Development
+
+Resources for and about the development of docstub.
+
+:::{toctree}
+:maxdepth: 1
+
+contributing
+release
+:::

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
+

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}

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"