🧑‍💻🤝 Contributing to afk-bot¶

Hello from the SlickML🧞 Team 👋 and welcome to our contributing guidelines 🤗. Here we laid out the details of the development process based on our coding standards, and we hope these guidelines ease the process for you. Please feel free to apply your revisions if you did not find these guidelines useful.

👩‍⚖️ Code of Conduct¶

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. By participating and contributing to this project, you agree to uphold our community standards 🙏.

🚀🌙 Getting Started¶

Please note that before starting any major work, open an issue describing what you are planning to work on. The best way to start is to check the good-first-issue label🏷 on the issue board. In this way, the SlickML team members and other interested parties can give you feedback on the opened issue 🙋‍♀️ regarding the possible idea 💡, bug 🪲, or feature 🧬. Additionally, it will reduce the chance of duplicated work and it would help us to manage the tasks in a parallel fashion; so your pull request would get merged faster 🏎 🏁. Whether the contributions consist of adding new features, optimizing the code-base, or assisting with the documentation, we welcome new contributors of all experience levels. The SlickML🧞 community goals are to be helpful and effective 🙌.

📐 Coding Standards¶

Long time Pythoneer 🐍 Tim Peters succinctly channels the BDFL’s guiding principles for Python’s design into 20 aphorisms, only 19 of which have been written down as Zen of Python 🧘‍♀️.
We try to follow Google Python Style Guide as much as possible.
We follow numpydoc style guidelines for docstrings 👌.
Every public and private function/method must have full type annotations (parameters + return type). Prefer precise types over Any.
Prefer keyword (named) arguments over positional calls.

🐍 🥷 Environment Management¶

To begin with, install a Python version >=3.10,<3.15.
All developments are done via uv. To begin with, first install uv following the installation documentation depending on your operating system.
Once you setup your environment, to install the dependencies (uv.lock), simply run 🏃‍♀️:
```
uv sync
```
Documentation build extras:
```
uv sync --group docs
```
We mainly use Poe the Poet, a pythonic task runner that works well with uv. Install the CLI once 🏃‍♀️:
```
uv tool install poethepoet
```
To make sure your environment is setup correctly, simply run 🏃‍♀️:
```
poe greet
```
For more options for task runners, simply run 🏃‍♀️:
```
poe --help
```

🛠 Formatting¶

To ease the process and reduce headache 💆‍♀️, we have serialized the required formatting commands to save more time ⏰. To apply all the required formatting steps, simply run 🏃‍♀️:
```
poe format
```
Formatting uses add-trailing-comma, isort (black profile), and black (line-length = 100).

🪓 Linting¶

To apply all the required linting steps, simply run 🏃‍♀️:
```
poe check
```
poe check runs black --check, isort --check-only, flake8, and mypy behind the scenes.
We use mypy with more specification laid out in mypy.ini. To apply mypy 🏃‍♀️:
```
poe mypy
```
To run lint + tests + build across supported Python versions, use tox (tox.ini):
```
poe tox
```

🧪 Testing¶

We mainly use pytest, assertpy along with pytest-cov with more specification laid out in .coveragerc.
All unit-tests live in tests/ directory separated from the source code.
All unit-test files should begin with the word test i.e. test_foo.py.
Our naming convention for naming tests is test_<method_under_test>__<when>__<then> pattern which would increase the code readability.
Prefer assertpy over bare assert in tests.
To run all unit-tests, simply run 🏃‍♀️:
```
poe test
```

📖 Documentation¶

We follow numpydoc style guidelines for docstrings syntax, and best practices 👌.
Sphinx docs live under docs/ (same layout as slick-tune): pages in docs/pages/, config in docs/conf.py.

Build HTML locally 🏃‍♀️:

uv sync --group docs
poe sphinx
# open docs/_build/index.html

Keep the product overview in README.md; keep contributor workflow details in this file.

🔥 Pull Requests¶

Please make sure to open an issue before starting major work and get core-team feedback.
Try to fix one bug or add one new feature per PR. This would minimize the amount of code changes and it is easier for code-review.
We recommend to follow Fork and Pull Request Workflow.
1. Fork our repository to your own Github account.
2. Clone the forked repository to your machine.
3. Create a branch locally; our naming conventions are bugfix/the-bug-i-fix and feature/the-new-feature-i-add for bug fixes and new features, respectively.
4. Please use present tense verbs for your commit messages i.e. Fix bug ..., Add feature ..., and avoid using past tense verbs.
5. Try to rebase the commits as much as possible to keep the git history clean.
6. Follow the formatting, linting, and testing guidelines above (poe format, poe check, poe test).
7. CI (GitHub Actions) runs the same gates — see .github/workflows/ci.yml.
8. Now, you are ready to push your changes to your forked repository.
9. Lastly, open a PR in our repository so that we can efficiently review the changes as soon as possible and get your feature/bug-fix merged.
10. Nicely done! You are all set! You are now officially part of afk-bot contributors.

❓ 🆘 📲 Need Help?¶

Please join our Slack Channel to interact directly with the core team and our small community. This is a good place to discuss your questions and ideas or in general ask for help 👨‍👩‍👧 👫 👨‍👩‍👦.