.. _contributing:

Contributing
============

Thank you for checking out EDSL! We sincerely appreciate feedback and welcome contributions to this project.

This page describes some ways to contribute to the project. 
It includes information on how to report bugs, suggest enhancements, draft new documentation pages, and contribute code.

Please also feel free to reach out to us in our Discord channel or by email if you have any questions or need help:

.. raw:: html

    <a href="https://discord.com/invite/mxAYkjfy9m" target="_blank"><i class="fab fa-discord"></i></a>&nbsp;&nbsp;<a href="https://discord.com/invite/mxAYkjfy9m" target="_blank">Discord channel</a>
    <br><br>


.. raw:: html

    <a href="mailto:info@expectedparrot.com"><i class="fas fa-envelope"></i></a>&nbsp;&nbsp;<a href="mailto:info@expectedparrot.com" target="_blank">info@expectedparrot.com</a>
    <br><br>


Reporting bugs
--------------

If you find a bug in the project, please let us know and report it on the project's GitHub issue tracker.
Link to the issue tracker:

.. raw:: html

    <a href="https://github.com/expectedparrot/edsl/issues/new" target="_blank">EDSL GitHub issue tracker</a>
    
    
When reporting a bug, it is helpful to include the following information:

- The version of the project you are using. (Run `edsl --version` to find the version number.)
- The operating system you are using. (For example, Windows, macOS, or Linux.)
- The Python version you are using. (Run `python --version` to find the Python version number.)
- A detailed description of the bug, including the steps to reproduce it. 
- If possible, a minimal example that reproduces the bug.

If you are able to fix the bug, please consider submitting a pull request with the fix (see below).


Suggesting enhancements
-----------------------

If you have an idea for an enhancement to the project, please let us know and report it on the project's GitHub issue tracker (see link above).

When suggesting an enhancement, it is helpful to include the following information:

- A detailed description of the enhancement.
- A rationale for the enhancement.
- If possible, a sketch of the proposed implementation.

If you do not wish to implement the enhancement yourself, please consider submitting a pull request with the changes (see below).


Drafting new documentation pages
--------------------------------

If you would like to contribute a new documentation page to the project, please follow these steps:

1. Fork the project on GitHub.
2. Create a new branch for your documentation page.
3. Add the new documentation page to the `docs/` directory.
4. Add a link to the new documentation page in the `docs/index.rst` file. 
5. Submit a pull request with your changes.

Please follow the project's documentation conventions when writing documentation (header styles, code blocks, links, etc.). 
For example, use the `reStructuredText` markup language and consider copying this or other pages as a template.


Contributing code
-----------------

If you would like to contribute code to the project, it is helpfup to follow these steps:

1. Fork the project on GitHub.
2. Create a new branch for your changes.
3. Write your code.
4. Write tests for your code.
5. Run the tests.
6. Submit a pull request with your changes.

When submitting a pull request, please include the following information:

- A description of the changes in the pull request.
- A rationale for the changes.
- If the changes fix a bug, please include the issue number.

When writing tests, please follow the project's testing conventions.
The project uses the `unittest` testing framework.


Thank you!