update developer docs (#96)

Co-authored-by: Cristian <[email protected]>

docs/development.md

@@ -4,6 +4,19 @@ hide:
 ---
 # Development
 
+## Building Your Development Environment
+
+### Quickstart Guide
+
+If you're already familiar with writing pylint rules, you can get started quickly by following these steps:
+
+```bash
+poetry install
+poetry run invoke build
+```
+
+You can then use `poetry run invoke pytest` to run the test suite.
+
 ## Contributing
 
 The project is packaged with a light development environment using `invoke` tasks to help with the local development of the project and to run tests.
@@ -43,6 +56,34 @@ class NautobotSpecificExampleChecker(BaseChecker):
 !!! note
     For a detailed overview of how you can specify versions take a look at [PEP440](https://peps.python.org/pep-0440/#version-specifiers). However, in general you should strive for as simple as possible version specifiers.
 
+### Writing the Rule
+
+#### Rule Message
+
+Each rule should have a unique message id. From the [Pylint documentation](https://pylint.pycqa.org/en/latest/development_guide/how_tos/custom_checkers.html#defining-a-message):
+
+> The message-id should be a 4-digit number, prefixed with a message category. There are multiple message categories, these being `C`, `W`, `E`, `F`, `R`, standing for `Convention`, `Warning`, `Error`, `Fatal` and `Refactoring`. The 4 digits should not conflict with existing checkers and the first 2 digits should consistent across the checker (except shared messages).
+
+You can run `poetry run pylint --load-plugins=pylint_nautobot --list-msgs-enabled` to see all the enabled messages in your environment and check if your desired message id is already in use. Pylint Nautobot does not have a strict convention for message ids, but it is recommended to use the `42xx` range for new rules.
+
+In addition to the unique message id, you must also provide a unique message symbol. This is an alias of the message id and it can be used wherever the message id can be used. The message symbol must start with "nb-". See the below example of a custom Pylint checker definition:
+
+```python
+class NautobotCodeLocationChangesChecker(BaseChecker):
+    """Visit 'import from' statements to find import locations that have moved in 2.0."""
+
+    version_specifier = ">=2,<3"
+
+    name = "nautobot-code-location-changes"
+    msgs = {
+        "E4251": (  # message id
+            "Import location has changed (%s -> %s).",  # template of displayed message
+            "nb-code-location-changed",  # message symbol
+            "Reference: https://docs.nautobot.com/projects/core/en/next/development/apps/migration/code-updates/",  # message description
+        )
+    }
+```
+
 ### Testing Rules in a Specific Nautobot App
 
 To test your new rules on another Nautobot project while developing, you can add your local `pylint-nautobot` environment in editable mode to it.
@@ -60,6 +101,9 @@ Install `pylint-nautobot` in editable mode from your cloned repo:
 > poetry add --editable /path/to/pylint-nautobot/
 ```
 
+!!! warning
+    Pylint Nautobot does not currently support Python 3.12, so you may need to run `poetry env use 3.11` before creating your poetry environment if your operating system defaults to Python 3.12.
+
 Enable and configure the `pylint-nautobot` plugin in the target App's `pyproject.toml`:
 
 ```
@@ -81,7 +125,7 @@ supported_nautobot_versions = [
 Test whether the new rules are enabled, replacing the message codes with your own, by running the following in the `nautobot-plugin-golden-config` folder:
 
 ```
-> poetry run pylint --list-msgs-enabled | grep E42
+> poetry run pylint --list-msgs-enabled | grep nb-
   nb-replaced-device-role (E4211)
   nb-replaced-rack-role (E4212)
   nb-replaced-ipam-role (E4213)