Require an "open for pull requests" issue label on PRs

Replace the pull request template with the new contribution policy: a pull
request must reference an issue in this repo that is open and carries the
"open for pull requests" label, or it is closed automatically.

The rule is deliberately without exceptions, including for documentation and
typo fixes, which the previous template explicitly waved through.  A rule with
exceptions is a rule that gets argued about on every pull request that lands
near the boundary, and the argument costs more than labeling a two line issue
does.  CONTRIBUTING describes the process and what each of the issue labels
means for a contributor.

The issue templates gain a note pointing at the same policy, so the
expectation is set when the issue is opened rather than when the pull request
is closed.

The gate is implemented as a github webhook handler in publishthing
(publishthing.apps.prgate), configured per project from build_ln.

Change-Id: Ibeb610214472bd262330508b83c99f3b1ff71436

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644 (file)
index 0000000..08da1d4
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,47 @@
+# Contributing to Alembic
+
+For general developer guidelines, please see our current Developer Guide at
+[Develop](https://www.sqlalchemy.org/develop.html).
+
+## Pull requests require an approved issue ##
+
+**We accept pull requests only for issues that a maintainer has marked with
+the `open for pull requests` label.**  A pull request that doesn't reference
+such an issue is closed automatically, by a bot, as soon as it's opened.
+
+The reason is that the vast majority of unsolicited pull requests are
+solutions to a problem we haven't agreed on yet, and reviewing them costs far
+more than writing them does.  Settling the approach on the issue first means
+nobody writes code that was never going to be merged.
+
+The process is:
+
+1. **Open an issue** describing the problem or the feature, with a complete,
+   runnable example.  For a bug, that means a script we can run that shows the
+   wrong behavior.
+2. **Wait for a maintainer** to look at it.  If we agree the change is wanted
+   and that an outside contribution is the right way to get it, we add the
+   `open for pull requests` label.
+3. **Then open the pull request**, referencing the issue.
+
+Some labels you'll see on issues, and what they mean for contributors:
+
+| label | meaning |
+| --- | --- |
+| `open for pull requests` | we'd welcome a pull request for this |
+| `code review in progress` | someone is already working on it, in a pull request or directly in gerrit |
+| `NO pull requests please` | we're handling this one ourselves; please don't |
+
+An issue with none of these labels hasn't been decided on yet.  Asking on the
+issue is fine; opening a pull request to make the case is not, and it will be
+closed.
+
+This applies to documentation and typo fixes too.  We know that feels heavy
+for a one-line change, but the alternative is a rule with exceptions that have
+to be argued about, and we'd rather have one rule.  A typo is a two-line issue
+and we'll label it quickly.
+
+## Note on use of AI, agents and bots ##
+
+Alembic follows the same policy as SQLAlchemy; please see
+[the SQLAlchemy contributing guide](https://github.com/sqlalchemy/sqlalchemy/blob/main/.github/CONTRIBUTING.md#note-on-use-of-ai-agents-and-bots).

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 280674a6dde6607f4d22e6dc72153fe385e87012..52622d3e9cdc3ae207e403501270844401f6fc21 100644 (file)
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -38,4 +38,9 @@ See also [Reporting Bugs](https://www.sqlalchemy.org/participate.html#bugs) on t
 **Additional context**
 <!-- Add any other context about the problem here. -->
 
+**Thinking of submitting a pull request for this?**  Please wait until a
+maintainer has added the `open for pull requests` label to this issue.  Pull
+requests that don't reference an issue carrying that label are closed
+automatically.
+
 **Have a nice day!**

diff --git a/.github/ISSUE_TEMPLATE/use_case.md b/.github/ISSUE_TEMPLATE/use_case.md
index 8677cb556fe1a52f6226b14e8e33863c6b6788a5..28381e63cde4b51ab4873bcc16b08b747393492f 100644 (file)
--- a/.github/ISSUE_TEMPLATE/use_case.md
+++ b/.github/ISSUE_TEMPLATE/use_case.md
@@ -21,4 +21,9 @@ assignees: ''
 **Additional context**
 <!-- Add any other context about the problem here. -->
 
+**Thinking of submitting a pull request for this?**  Please wait until a
+maintainer has added the `open for pull requests` label to this issue.  Pull
+requests that don't reference an issue carrying that label are closed
+automatically.
+
 **Have a nice day!**

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 01bdac9c973549a5dd053d9c2f1c1f2853b4ed51..a09214bbb9b2104315e86ab782092a95e1550e92 100644 (file)
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,27 +1,33 @@
 <!-- Provide a general summary of your proposed changes in the Title field above -->
 
+**This project accepts pull requests only for issues that a maintainer has
+marked with the `open for pull requests` label.**
+
+A pull request that doesn't reference such an issue **is closed
+automatically**. That isn't a judgment on your change: it's how we settle on
+an approach before anyone spends time writing code, and how we keep two
+people from doing the same work at once.
+
+The issue you reference has to be:
+
+* in this repository,
+* open,
+* labeled `open for pull requests`, and
+* not already labeled `code review in progress`, which means someone is
+  working on it already.
+
+If there's no such issue yet, open one describing the problem or the feature,
+including a complete, runnable example, and wait for a maintainer to add the
+label. Please don't open a pull request first and ask for the label
+afterwards.
+
+### Fixes
+
+<!-- Put the issue number after the "#" below, e.g. "Fixes: #1234".
+     Leaving this blank means this pull request will be closed. -->
+
+Fixes: #
+
 ### Description
-<!-- Describe your changes in detail -->
-
-### Checklist
-<!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once)
-
--->
-
-This pull request is:
-
-- [ ] A documentation / typographical error fix
-       - Good to go, no issue or tests are needed
-- [ ] A short code fix
-       - please include the issue number, and create an issue if none exists, which
-         must include a complete example of the issue.  one line code fixes without an
-         issue and demonstration will not be accepted.
-       - Please include: `Fixes: #<issue number>` in the commit message
-       - please include tests.   one line code fixes without tests will not be accepted.
-- [ ] A new feature implementation
-       - please include the issue number, and create an issue if none exists, which must
-         include a complete example of how the feature would look.
-       - Please include: `Fixes: #<issue number>` in the commit message
-       - please include tests.
-
-**Have a nice day!**
+
+<!-- Describe your changes in detail. -->