Add contribution, release & style guide (#103)

* Draft a guide for the release process

* Update project URLs in pyproject.toml

* Draft contribution guide

* Complete release guide

* Tweak contribution guide

* Add design & style guide

* Overwrite org CONTRIBUTION guide

See
https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

* Tweak contribution and installation guides

Author: lagru

.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)

docs/development/contributing.md

@@ -0,0 +1,68 @@
+# Contributing
+
+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.
+
+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
+
+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/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!

docs/development/index.md

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

docs/development/release.md

@@ -0,0 +1,73 @@
+# 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
+
+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
+
+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
+
+[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.

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}

docs/installation.md

@@ -12,12 +12,16 @@ 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
 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).
+:::
+

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"