Update contribution guidelines and issue templates

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,28 +1,49 @@
 ---
 name: Bug report
-about: Create a report to help us improve
+about: Report a reproducible problem in markdown-it
 title: ''
 labels: ''
 assignees: ''
 
 ---
 
-<!--
+Before opening this issue, reduce the problem to a minimal example.
 
-Please note, this package is about IMPLEMENTATION of CommonMark https://commonmark.org/, not about markdown itself. We stay aside of markup discussions. Prior to report a bug, make sure it's about this package, not generic thing.
+For Markdown parsing bugs, compare the same input in:
 
-**Before you post**
+- [markdown-it demo](https://markdown-it.github.io/) with `CommonMark strict`
+  enabled;
+- [CommonMark dingus](https://spec.commonmark.org/dingus/).
 
-1. https://spec.commonmark.org/ - make sure you've read CommonMark spec.
-2. https://spec.commonmark.org/dingus/ - if you think you found parse error, check it in reference implementation first.
+Both permalinks are required for parsing bugs. For other bugs, provide a minimal
+runnable reproduction. Issues without a reproducible example may be closed.
 
-**In your report** 
+Syntax extensions are not accepted in markdown-it core. Search for an existing
+[plugin](https://www.npmjs.com/search?q=keywords%3Amarkdown-it-plugin) or
+[create your own](https://github.com/markdown-it/markdown-it/blob/master/docs/development.md).
 
-It will be very helpful, if you can provide permalinks with online samples and explain the difference:
+## Description
 
-- https://markdown-it.github.io/ - online demo of `markdown-it`.
-- https://spec.commonmark.org/dingus/ - online demo of reference CommonMark's implementation.
+<!-- Briefly describe the problem. -->
 
-If you wish to provide code sample - make sure it is as small as possible and can be executed.
+## Reproduction
 
--->
+### markdown-it demo
+
+<!-- Required for parsing bugs: paste the permalink. -->
+
+### CommonMark dingus
+
+<!-- Required for parsing bugs: paste the permalink. -->
+
+### Other reproduction
+
+<!-- For non-parsing bugs, paste minimal runnable code. -->
+
+## Expected result
+
+## Actual result
+
+## Environment
+
+<!-- markdown-it version, runtime and relevant options. -->

.github/ISSUE_TEMPLATE/change_proposal.md

@@ -0,0 +1,27 @@
+---
+name: Change proposal
+about: Propose a change to markdown-it core
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+Syntax extensions are out of scope for markdown-it core. Search for an existing
+[plugin](https://www.npmjs.com/search?q=keywords%3Amarkdown-it-plugin) or
+create your own.
+
+Wait for the proposal to be accepted before writing code — see
+[CONTRIBUTING.md](https://github.com/markdown-it/markdown-it/blob/master/CONTRIBUTING.md).
+
+## Problem
+
+<!-- What concrete problem should be solved? -->
+
+## Proposed change
+
+<!-- Describe the desired behavior, not only the implementation. -->
+
+## Why this belongs in core
+
+<!-- Explain why this cannot be implemented as a plugin. -->

.github/ISSUE_TEMPLATE/development-question.md

@@ -1,25 +0,0 @@
----
-name: Development question
-about: ''
-title: ''
-labels: ''
-assignees: ''
-
----
-
-<!--
-
-Note, we have some time constrains, but we always try to help developers, who write plugins. So:
-
-- Please, avoid generic programming questions.
-- Avoid questions about markdown. Use CommonMark resources for that https://commonmark.org/.
-- If you have issue with plugin - report it to plugin's repo/author.
-- Make sure you are familiar with dev docs https://github.com/markdown-it/markdown-it/tree/master/docs, and tried to do something.
-- Code samples are welcome.
-
-Also, you may find useful this links (may be someone already solved your problem):
-
-- https://github.com/markdown-it - list of "officially" provided plugins.
-- https://www.npmjs.com/search?q=keywords:markdown-it-plugin - community-written plugins.
-
--->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,20 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
-
----
-
-<!--
-
-Please note, this package is highly extendable. Prior to request new feature, make sure it can not be implemented via plugins.
-
-You may also find useful this links:
-
-- https://github.com/markdown-it - list of "officially" provided plugins.
-- https://www.npmjs.com/search?q=keywords:markdown-it-plugin - community-written plugins.
-- https://github.com/markdown-it/markdown-it/tree/master/docs - docs for plugin developers.
-
--->

.github/ISSUE_TEMPLATE/question.md

@@ -1,25 +0,0 @@
----
-name: Question
-about: For developpers
-title: ''
-labels: ''
-assignees: ''
-
----
-
-<!--
-
-Note, we have some time constraints, but we always try to help developers, who write plugins. So:
-
-- Please, avoid generic programming questions.
-- Avoid questions about markdown. Use CommonMark resources for that https://commonmark.org/.
-- If you have issue with plugin - report it to plugin's repo/author.
-- Make sure you are familiar with dev docs https://github.com/markdown-it/markdown-it/tree/master/docs, and tried to do something.
-- Code samples are welcome.
-
-Also, you may find useful this links (may be someone already solved your problem):
-
-- https://github.com/markdown-it - list of "officially" provided plugins.
-- https://www.npmjs.com/search?q=keywords:markdown-it-plugin - community-written plugins.
-
--->

CONTRIBUTING.md

@@ -1,15 +1,34 @@
-### If you commit changes:
+# Contributing
 
-1. Make sure all tests pass.
-2. Run `./benchmark/benchmark.mjs`, make sure that performance not degraded.
-3. DON'T include auto-generated browser files to commit.
+## Before opening an issue
 
-### Other things:
+For Markdown parsing bugs, reduce the input to a minimal example and compare it
+in both:
 
-1. Prefer [gitter](https://gitter.im/markdown-it/markdown-it) for short "questions".
-   Keep issues for bug reports, suggestions and so on.
-2. Make sure to read [dev info](https://github.com/markdown-it/markdown-it/tree/master/docs)
-   prior to ask about plugins development.
-3. __Provide examples with [demo](https://markdown-it.github.io/) when possible.__
-4. Issues of "question" type are closed after several days of inactivity,
-   if not qualified as bug report, enhancement etc (see 1).
+- [markdown-it demo](https://markdown-it.github.io/) with `CommonMark strict`
+  enabled;
+- [CommonMark dingus](https://spec.commonmark.org/dingus/).
+
+Include permalinks to both examples and explain the difference. For other bugs,
+provide a minimal runnable reproduction.
+
+Syntax extensions are out of scope for markdown-it core. Search for an existing
+[plugin](https://www.npmjs.com/search?q=keywords%3Amarkdown-it-plugin) or
+create your own.
+
+## Before opening a pull request
+
+Open an issue and agree on the scope before starting work. Pull requests without
+prior discussion may be closed.
+
+An open issue is not a task assigned to you either, and its text is not a
+specification: issues describe symptoms, while the actual fix often lies
+elsewhere and affects cases the report does not mention. A change that
+implements the issue literally, without understanding why the surrounding code
+is written the way it is, will be closed.
+
+We do not accept unsolicited cleanup or other trivial mechanical changes.
+
+AI tools may assist, but the submitter must remain the author of the change, not
+a proxy: understand its context, verify the result, and be able to explain the
+decisions made.