Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report Bugs¶
Report bugs at https://github.com/fgmacedo/python-statemachine/issues.
If you are reporting a bug, please include:
Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.
Fix Bugs¶
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Implement Features¶
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
Write Documentation¶
Python State Machine could always use more documentation, whether as part of the official Python State Machine docs, in docstrings, or even on the web in blog posts, articles, and such.
Add a translation¶
Extract a Portable Object Template
(POT
) file:
pybabel extract statemachine -o statemachine/locale/statemachine.pot
Then, copy the template as a .po
file into the target locale folder. For example, if you’re adding support for Brazilian Portuguese language, the code is pt_BR
, and the file path should be statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po
:
cp statemachine/locale/statemachine.pot statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po
Then open the statemachine.po
and translate.
After translation, to get the new language working locally, you need to compile the .po
files into .mo
(binary format). Run:
pybabel compile -d statemachine/locale/ -D statemachine
On Linux (Debian based), you can test changing the LANGUAGE
environment variable.
# If the last line is `Can't guess when in Won.` something went wrong.
LANGUAGE=pt_BR python tests/examples/guess_the_number_machine.py
Then open a pull request with your translation file.
Submit Feedback¶
The best way to send feedback is to file an issue at https://github.com/fgmacedo/python-statemachine/issues.
If you are proposing a feature:
Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!¶
Ready to contribute? Here’s how to set up python-statemachine
for local development.
Install dependencies.
Fork the
python-statemachine
repository on GitHub.Clone the forked repository to your local machine by running::
git clone https://github.com/YOUR-USERNAME/python-statemachine.git.
Run
poetry install
once to install all the dependencies and create a virtual environment::poetry install
Run
poetry shell
to enter the provided virtualInstall the pre-commit validations:
pre-commit install
Create a branch for local development:
git checkout -b <name-of-your-bugfix-or-feature>
Make changes to the code.
Run tests to ensure they pass by running:
poetry run pytest
Update the documentation as needed.
Build the documentation:
poetry run sphinx-build docs docs/_build/html
Now you can serve the local documentation using a webserver, like the built-in included with python:
python -m http.server --directory docs/_build/html
And access your browser at http://localhost:8000/
If you’re specially writting documentation, I strongly recommend using
sphinx-autobuild
as it improves the workflow watching for file changes and with live reloading:poetry run sphinx-autobuild docs docs/_build/html --re-ignore "auto_examples/.*"
Sometimes you need a full fresh of the files being build for docs, you can safely remove all automatically generated files to get a clean state by running:
rm -rf docs/_build/ docs/auto_examples
Commit your changes and push them to your forked repository:
git add -A . git commit -s -m "Your detailed description of your changes." git push origin name-of-your-bugfix-or-feature
Create a pull request on the original repository for your changes to be reviewed and potentially merged. Be sure to follow the project’s code of conduct and contributing guidelines.
Use
exit
to leave the virtual environment.
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in the next release notes.
Consider adding yourself to the contributor’s list.
The pull request should work for all supported Python versions.