From eb63eddce1786cae68dd9a0f7e3dfca570a70fa7 Mon Sep 17 00:00:00 2001
From: Bruce Weirdan <weirdan@gmail.com>
Date: Wed, 15 Feb 2023 23:12:14 -0400
Subject: [PATCH] Added a page explaining how to add a new issue type

---
 docs/contributing/adding_issues.md | 62 ++++++++++++++++++++++++++++++
 docs/contributing/index.md         |  1 +
 2 files changed, 63 insertions(+)
 create mode 100644 docs/contributing/adding_issues.md

diff --git a/docs/contributing/adding_issues.md b/docs/contributing/adding_issues.md
new file mode 100644
index 000000000..b609d8728
--- /dev/null
+++ b/docs/contributing/adding_issues.md
@@ -0,0 +1,62 @@
+# Adding a new issue type
+
+To add a new issue type there are a number of required steps, listed below.
+
+## Generating a new shortcode
+
+Run `bin/max_used_shortcode.php` and note the value it printed (`$max_shortcode`)
+
+## Create issue class
+
+Create a class in `Psalm\Issue` namespace like this:
+
+```php
+<?php
+
+namespace Psalm\Issue;
+
+final class MyNewIssue extends CodeIssue 
+{
+    public const SHORTCODE = 123;
+    public const ERROR_LEVEL = 2;
+}
+```
+
+For `SHORTCODE` value use `$max_shortcode + 1`. To choose appropriate error level see [Error levels](../running_psalm/error_levels.md).
+
+There a number of abstract classes you can extend:
+
+* `CodeIssue` - non specific, default issue. It's a base class for all issues.
+* `ClassIssue` - issue related to a specific class (also interface, trait, enum). These issues can be suppressed for specific classes in `psalm.xml` by using `referencedClass` attribute
+* `PropertyIssue` - issue related to a specific property. Can be targeted by using `referencedProperty` in `psalm.xml`
+* `FunctionIssue` - issue related to a specific function. Can be suppressed with `referencedFunction` attribute.
+* `ArgumentIssue` - issue related to a specific argument. Can be targeted with `referencedFunction` attribute.
+* `MethodIssue` - issue related to a specific method. Can be targeted with `referencedMethod` attribute.
+* `ClassConstantIssue` - issue related ot a specific class constant. Can be targeted with `referencedConstant`.
+* `VariableIssue` - issue for a specific variable. Targeted with `referencedVariable`
+
+## Add a `config.xsd` entry
+
+All issue types needs to be listed in `config.xsd`, which is used to validate `psalm.xml`. Choose appropriate `type` attribute. E.g. for issues extending `PropertyIssue` use `type="PropertyIssueHandlerType"`.
+
+## Add a doc page for your new issue
+
+Every issue needs to be documented. Create a markdown file in `docs/running_psalm/issues` folder. Make sure to include a snippet of code illustrating your issue. Important: snippets must use fenced php code block and must include opening PHP tag (`<?php`). The snippet must actually produce the issue you're documenting. It's checked by our test suite.
+
+## Add links to the doc page
+
+Add links to the doc page you created to `docs/running_psalm/error_levels.md` and `docs/running_psalm/issues.md`
+
+## Run documentation tests
+
+```
+$ vendor/bin/phpunit tests/DocumentationTest.php
+```
+
+It will check whether you did all (or at least most) of the steps above.
+
+## Use your new issue type in Psalm core
+
+```php
+IssueBuffer::maybeAdd(new MyNewIssue(...))
+```
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
index 774a95e70..f4120eb95 100644
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@@ -29,6 +29,7 @@ Lastly, working to improve static analysis tools will also make you a better PHP
 ### Guides
 
 * [Editing callmaps](editing_callmaps.md)
+* [Adding a new issue type](adding_issues.md)
 
 ## Pull Requests