Merge pull request #839 from xizheyin/behind-upstream

Add doc for triagebot [behind-upstream] handler

Author: Urgau

src/SUMMARY.md

@@ -16,6 +16,7 @@
     - [PR Assignment](./triagebot/pr-assignment.md)
     - [Tracking PR assignment](./triagebot/pr-assignment-tracking.md)
     - [Autolabels](./triagebot/autolabels.md)
+    - [Behind Upstream](./triagebot/behind-upstream.md)
     - [Canonicalize Issue Links](./triagebot/canonicalize-issue-links.md)
     - [Close](./triagebot/close.md)
     - [Documentation Updates](./triagebot/doc-updates.md)

src/triagebot/behind-upstream.md

@@ -0,0 +1,30 @@
+# Behind Upstream
+
+This handler checks if a PR is based on an *X* days old commit.
+
+## Context
+
+When a PR's code is based on a very old commit from an upstream branch:
+It passes when tested locally, but fails when the PR is submitted for testing through CI.
+
+This is because the CI applies the commit patches to the current upstream branch,
+which may have new test cases, so it won't pass. We need to rebase the PR to the nearest upstream branch.
+
+## Configuration
+
+> The default threshold is currently set at **7 days**.
+
+This feature is enabled on a repository by having a `[behind-upstream]` table in `triagebot.toml`:
+
+```toml
+[behind-upstream]
+```
+or, you can set the day threshold,
+```toml
+[behind-upstream]
+days-threshold = 7
+```
+
+## Implementation
+
+See [`src/handlers/check_commits/behind_upstream.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/check_commits/behind_upstream.rs).