ci: fail a pull request that waits for an unmerged gitea change

README.md

@@ -48,6 +48,27 @@ The order of the top level sidebar groups comes from `sidebars.js` (and
 `versioned_sidebars/` for released versions), the label and order of every other
 group from the `_category_.json` of its directory.
 
+### Documenting an unreleased feature
+
+A page that describes a gitea change which is not merged yet must wait for it,
+otherwise the site documents something no release has. Say so in the description
+of the pull request:
+
+```
+Depends on: gitea#35851
+```
+
+The `depends-upstream` check reads those references (`gitea#<id>` or the full
+pull request url, several are allowed) and fails while any of them is unmerged,
+which blocks the merge since `main` requires the `checks` contexts. Add the
+`depends-on-upstream` label as well, so the pull request is easy to find; the
+label alone fails the check, it has to be accompanied by a reference.
+
+The `unlabel merged upstream dependencies` job runs every 6 hours, removes the
+label once every referenced pull request is merged and comments on the pull
+request, which reruns the check. `scripts/check-upstream-deps.sh` is the check
+itself and can be run locally against the json of a pull request.
+
 ## Cutting a version
 
 ```shell