============================
Contributing to `jsonschema`
============================

Found a bug?
------------

If you suspect you may have found a security-related vulnerability, please follow the instructions in `the security policy <https://github.com/python-jsonschema/jsonschema/blob/main/.github/SECURITY.md>`_.

Otherwise, it is extremely helpful if you first search to see whether your bug has been `previously reported on the Issues tab <https://github.com/python-jsonschema/jsonschema/issues?q=is%3Aissue+is%3Aopen+label%3ABug>`_.

If it doesn't appear to be a known issue, please `file a new one <https://github.com/python-jsonschema/jsonschema/issues/new>`_, and include a **title and clear description**, along with as much relevant information as possible.
Including a *minimal*, *self-sufficient* bit of code (often an instance and schema) is the fastest way to get attention, along with a description of the behavior you expect, and if you're able, a link to where in the specification contains the behavior you're noticing is incorrect.

Pull requests to fix your issue are of course very welcome.


Fixing a Bug?
-------------

Please open a new GitHub pull request with the change, along with new tests.

Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.

Continuous integration via GitHub actions should run to indicate whether your change passes both the test suite as well as linters.
Please ensure it passes, or indicate in a comment if you believe it fails spuriously.


Adding New Functionality?
-------------------------

Please discuss any larger changes ahead of time for the sake of your own time!

Improvements are very welcome, but large pull requests, disruptive ones, or backwards incompatible ones, can lead to long back and forth discussions.

You're welcome to suggest a change in an issue and thereby get some initial feedback before embarking on an effort that may not get merged.


Improving the Documentation?
----------------------------

Writing good documentation is challenging both to prioritize and to do well.

Any help you may have would be great, especially if you're a beginner who's struggled to understand a part of the library.

Documentation is written in `Sphinx-flavored reStructuredText <https://www.sphinx-doc.org>`_, so you'll want to familiarize yourself a bit with Sphinx.

Feel free to file issues or pull requests.


Have a Question?
----------------

Please do not use the issue tracker for questions, it's reserved for things believed to be bugs, or new functionality.

There is a `discussions tab <https://github.com/python-jsonschema/jsonschema/discussions>`_ where general questions can be asked.

Answers on it are best-effort.

Any help you can offer to answer others' questions is of course very welcome as well.