python/aiogram
1
0
Fork 0
mirror of https://github.com/aiogram/aiogram.git synced 2026-04-08 16:37:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added contributing guide

Browse source
This commit is contained in:
Alex Root Junior 2023-01-12 02:39:40 +02:00
parent 977f98a425
commit 80de75a96e
No known key found for this signature in database
GPG key ID: 074C1D455EBEA4AC
8 changed files with 230 additions and 140 deletions
Download patch file Download diff file Expand all files Collapse all files

6
.readthedocs.yml
View file

@ -1,11 +1,13 @@
version: 2
python:
version: "3.8"
version: "3.10"
install:
- method: pip
path: .
- requirements: requirements/docs.txt
extra_requirements:
- docs
- redis
sphinx:
configuration: docs/conf.py

2
CHANGES/1095.misc.rst
View file

@ -1 +1 @@
Updated package metadata, moved build internals from Poetry to Hatch
Updated package metadata, moved build internals from Poetry to Hatch, added contributing guides.

1
CONTRIBUTING.md Normal file
View file

@ -0,0 +1 @@
Please read the [Contributing](https://docs.aiogram.dev/en/dev-3.x/contributing/) guidelines in the documentation site.

66
Makefile
View file

@ -1,8 +1,4 @@
.DEFAULT_GOAL := help
base_python := python3
py := poetry run
python := $(py) python
.DEFAULT_GOAL := lint
package_dir := aiogram
tests_dir := tests
@ -13,43 +9,10 @@ reports_dir := reports
redis_connection := redis://localhost:6379
.PHONY: help
help:
@echo "======================================================================================="
@echo " aiogram build tools "
@echo "======================================================================================="
@echo "Environment:"
@echo " help: Show this message"
@echo " install: Install development dependencies"
@echo " clean: Delete temporary files"
@echo ""
@echo "Code quality:"
@echo " lint: Lint code by isort, black, flake8 and mypy tools"
@echo " reformat: Reformat code by isort and black tools"
@echo ""
@echo "Tests:"
@echo " test: Run tests"
@echo " test-coverage: Run tests with HTML reporting (results + coverage)"
@echo " test-coverage-report: Open coverage report in default system web browser"
@echo ""
@echo "Documentation:"
@echo " docs: Build docs"
@echo " docs-serve: Serve docs for local development"
@echo " docs-prepare-reports: Move all HTML reports to docs dir"
@echo ""
@echo "Project"
@echo " build: Run tests build package and docs"
@echo ""
# =================================================================================================
# Environment
# =================================================================================================
.PHONY: install
install:
poetry install --all-extras
$(py) pre-commit install
.PHONY: clean
clean:
rm -rf `find . -name __pycache__`
@ -87,17 +50,17 @@ test-run-services:
.PHONY: test
test: test-run-services
$(py) pytest --cov=aiogram --cov-config .coveragerc tests/ --redis $(redis_connection)
pytest --cov=aiogram --cov-config .coveragerc tests/ --redis $(redis_connection)
.PHONY: test-coverage
test-coverage: test-run-services
mkdir -p $(reports_dir)/tests/
$(py) pytest --cov=aiogram --cov-config .coveragerc --html=$(reports_dir)/tests/index.html tests/ --redis $(redis_connection)
$(py) coverage html -d $(reports_dir)/coverage
pytest --cov=aiogram --cov-config .coveragerc --html=$(reports_dir)/tests/index.html tests/ --redis $(redis_connection)
coverage html -d $(reports_dir)/coverage
.PHONY: test-coverage-view
test-coverage-view:
$(py) coverage html -d $(reports_dir)/coverage
coverage html -d $(reports_dir)/coverage
python -c "import webbrowser; webbrowser.open('file://$(shell pwd)/reports/coverage/index.html')"
# =================================================================================================
@ -116,7 +79,7 @@ docs-gettext:
docs-serve:
#rm -rf docs/_build
$(py) sphinx-autobuild --watch aiogram/ --watch CHANGELOG.rst --watch README.rst docs/ docs/_build/ $(OPTS)
sphinx-autobuild --watch aiogram/ --watch CHANGELOG.rst --watch README.rst docs/ docs/_build/ $(OPTS)
.PHONY: docs-serve
$(locale_targets): docs-serve-%:
@ -128,15 +91,13 @@ $(locale_targets): docs-serve-%:
# =================================================================================================
.PHONY: build
build: clean flake8-report mypy-report test-coverage
mkdir -p site/simple
poetry build
mv dist site/simple/aiogram
build: clean
hatch build
.PHONY: bump
bump:
poetry version $(args)
$(python) scripts/bump_versions.py
hatch version $(args)
python scripts/bump_versions.py
.PHONY: towncrier-build
towncrier-build:
@ -159,10 +120,3 @@ release:
git add .
git commit -m "Release $(shell poetry version -s)"
git tag v$(shell poetry version -s)
_poetry_export_args := --format requirements.txt --without-hashes
.PHONY: export-requirements
export-requirements:
poetry export $(_poetry_export_args) --output requirements/base.txt
poetry export $(_poetry_export_args) --output requirements/docs.txt -E fast -E redis -E proxy -E i18n --with docs

213
docs/contributing.rst Normal file
View file

@ -0,0 +1,213 @@
============
Contributing
============
You're welcome to contribute to aiogram!
*aiogram* is an open-source project, and anyone can contribute to it in any possible way
Developing
==========
Before making any changes in the framework code, it is necessary to fork the project and clone
the project to your PC and know how to do a pull-request.
How to work with pull-request you can read in the `GitHub docs <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_
Also in due to this project is written in Python, you will need Python to be installed
(is recommended to use latest Python versions, but any version starting from 3.8 can be used)
Use virtualenv
--------------
You can create a virtual environment in a directory using :code:`venv` module (it should be pre-installed by default):
.. code-block::bash
python -m venv .venv
This action will create a :code:`.venv` directory with the Python binaries and then you will
be able to install packages into that isolated environment.
Activate the environment
------------------------
Linux/ macOS:
.. code-block:: bash
source .venv/bin/activate
Windows PoweShell
.. code-block:: powershell
.\.venv\Scripts\Activate.ps1
To check it worked, use described command, it should show the :code:`pip` location inside
the isolated environment
Linux, macOS:
.. code-block::
which pip
Windows PowerShell
.. code-block::
Get-Command pip
Also make you shure you have the latest pip version in your virtual environment to avoid
errors on next steps:
.. code-block::
python -m pip install --upgrade pip
Setup project
-------------
After activating the environment install `aiogram` from sources and their dependencies:
.. code-block:: bash
pip install -e ."[dev,test,docs,fast,redis,proxy,i18n]"
It will install :code:`aiogram` in editable mode into your virtual environment and all dependencies.
Making changes in code
----------------------
At this point you can make any changes in the code that you want, it can be any fixes,
implementing new features or experimenting.
Format the code (code-style)
----------------------------
Note that this project is Black-formatted, so you should follow that code-style,
too be sure You're correctly doing this let's reformat the code automatically:
.. code-block:: bash
black aiogram tests examples
isort aiogram tests examples
Run tests
---------
All changes should be tested:
.. code-block:: bash
pytest tests
Also if you are doing something with Redis-storage, you will need to test everything works with Redis:
.. code-block:: bash
pytest --redis redis://<host>:<port>/<db> tests
Docs
----
We are using `Sphinx` to render docs in different languages, all sources located in `docs` directory,
you can change the sources and to test it you can start live-preview server and look what you are doing:
.. code-block:: bash
sphinx-autobuild --watch aiogram/ docs/ docs/_build/
Docs translations
-----------------
Translation of the documentation is very necessary and cannot be done without the help of the
community from all over the world, so you are welcome to translate the documentation
into different languages.
Before start, let's up to date all texts:
.. code-block:: bash
cd docs
make gettext
sphinx-intl update -p _build/gettext -l <language_code>
Change the :code:`<language_code>` in example below to the target language code, after that
you can modify texts inside :code:`docs/locale/<language_code>/LC_MESSAGES` as :code:`*.po` files
by using any text-editor or specialized utilites for GNU Gettext,
for example via `poedit <https://poedit.net/>`_.
To view results:
.. code-block:: bash
sphinx-autobuild --watch aiogram/ docs/ docs/_build/ -D language=<language_code>
Describe changes
----------------
Describe your changes in one or more sentences so that bot developers know what's changed
in their favorite framework - create `<code>.<category>.rst` file and write the description.
:code:`<code>` is Issue or Pull-request number, after release link to this issue will
be published to the *Changelog* page.
:code:`<category>` is a changes category marker, it can be one of:
- :code:`feature` - when you are implementing new feature
- :code:`bugfix` - when you fix a bug
- :code:`doc` - when you improve the docs
- :code:`removal` - when you remove something from the framework
- :code:`misc` - when changed something inside the Core or project configuration
If you have troubles with changing category feel free to ask Core-contributors to help with choosing it.
Complete
--------
After you have made all your changes, publish them to the repository and create a pull request
as mentioned at the beginning of the article and wait for a review of these changes.
Star on GitHub
==============
You can "star" repository on GitHub - https://github.com/aiogram/aiogram (click the star button at the top right)
Adding stars makes it easier for other people to find this project and understand how useful it is.
Guides
======
You can write guides how to develop Bots on top of aiogram and publish it into YouTube, Medium,
GitHub Books, any Courses platform or any other platform that you know.
This will help more people learn about the framework and learn how to use it
Take answers
============
The developers is always asks for any question in our chats or any other platforms like GitHub Discussions,
StackOverflow and others, feel free to answer to this questions.
Funding
=======
The development of the project is free and not financed by commercial organizations,
it is my personal initiative (`@JRootJunior <https://t.me/JRootJunior>`_) and
I am engaged in the development of the project in my free time.
So, if you want to financially support the project, or, for example, give me a pizza or a beer,
you can do it on `OpenCollective <https://opencollective.com/aiogram>`_
or `Patreon <https://www.patreon.com/aiogram>`_.

1
docs/index.rst
View file

@ -16,3 +16,4 @@ Contents
dispatcher/index
utils/index
changelog
contributing

16
requirements/base.txt
View file

@ -1,16 +0,0 @@
aiofiles==22.1.0 ; python_version >= "3.8" and python_version < "4.0"
aiohttp==3.8.3 ; python_version >= "3.8" and python_version < "4.0"
aiosignal==1.2.0 ; python_version >= "3.8" and python_version < "4.0"
async-timeout==4.0.2 ; python_version >= "3.8" and python_version < "4.0"
attrs==22.1.0 ; python_version >= "3.8" and python_version < "4.0"
babel==2.10.3 ; python_version >= "3.8" and python_version < "4.0"
certifi==2022.9.24 ; python_version >= "3.8" and python_version < "4.0"
charset-normalizer==2.1.1 ; python_version >= "3.8" and python_version < "4.0"
frozenlist==1.3.1 ; python_version >= "3.8" and python_version < "4.0"
idna==3.4 ; python_version >= "3.8" and python_version < "4.0"
magic-filter==1.0.9 ; python_version >= "3.8" and python_version < "4.0"
multidict==6.0.2 ; python_version >= "3.8" and python_version < "4.0"
pydantic==1.10.2 ; python_version >= "3.8" and python_version < "4.0"
pytz==2022.5 ; python_version >= "3.8" and python_version < "4.0"
typing-extensions==4.4.0 ; python_version >= "3.8" and python_version < "4.0"
yarl==1.8.1 ; python_version >= "3.8" and python_version < "4.0"

65
requirements/docs.txt
View file

@ -1,65 +0,0 @@
aiofiles==22.1.0 ; python_version >= "3.8" and python_version < "4.0"
aiohttp-socks==0.7.1 ; python_version >= "3.8" and python_version < "4.0"
aiohttp==3.8.3 ; python_version >= "3.8" and python_version < "4.0"
aiosignal==1.2.0 ; python_version >= "3.8" and python_version < "4.0"
alabaster==0.7.12 ; python_version >= "3.8" and python_version < "4.0"
async-timeout==4.0.2 ; python_version >= "3.8" and python_version < "4.0"
attrs==22.1.0 ; python_version >= "3.8" and python_version < "4.0"
babel==2.10.3 ; python_version >= "3.8" and python_version < "4.0"
beautifulsoup4==4.11.1 ; python_version >= "3.8" and python_version < "4.0"
certifi==2022.9.24 ; python_version >= "3.8" and python_version < "4.0"
charset-normalizer==2.1.1 ; python_version >= "3.8" and python_version < "4.0"
click-default-group==1.2.2 ; python_version >= "3.8" and python_version < "4.0"
click==8.1.3 ; python_version >= "3.8" and python_version < "4.0"
colorama==0.4.6 ; python_version >= "3.8" and python_version < "4.0"
deprecated==1.2.13 ; python_version >= "3.8" and python_version < "4.0"
docutils==0.19 ; python_version >= "3.8" and python_version < "4.0"
frozenlist==1.3.1 ; python_version >= "3.8" and python_version < "4.0"
furo==2022.9.29 ; python_version >= "3.8" and python_version < "4.0"
idna==3.4 ; python_version >= "3.8" and python_version < "4.0"
imagesize==1.4.1 ; python_version >= "3.8" and python_version < "4.0"
importlib-metadata==5.0.0 ; python_version >= "3.8" and python_version < "3.10"
incremental==22.10.0 ; python_version >= "3.8" and python_version < "4.0"
jinja2==3.1.2 ; python_version >= "3.8" and python_version < "4.0"
livereload==2.6.3 ; python_version >= "3.8" and python_version < "4.0"
magic-filter==1.0.9 ; python_version >= "3.8" and python_version < "4.0"
markdown-include==0.7.0 ; python_version >= "3.8" and python_version < "4.0"
markdown==3.4.1 ; python_version >= "3.8" and python_version < "4.0"
markupsafe==2.1.1 ; python_version >= "3.8" and python_version < "4.0"
multidict==6.0.2 ; python_version >= "3.8" and python_version < "4.0"
packaging==21.3 ; python_version >= "3.8" and python_version < "4.0"
pydantic==1.10.2 ; python_version >= "3.8" and python_version < "4.0"
pygments==2.13.0 ; python_version >= "3.8" and python_version < "4.0"
pymdown-extensions==9.7 ; python_version >= "3.8" and python_version < "4.0"
pyparsing==3.0.9 ; python_version >= "3.8" and python_version < "4.0"
python-socks[asyncio]==2.0.3 ; python_version >= "3.8" and python_version < "4.0"
pytz==2022.5 ; python_version >= "3.8" and python_version < "4.0"
redis==4.3.4 ; python_version >= "3.8" and python_version < "4.0"
requests==2.28.1 ; python_version >= "3.8" and python_version < "4"
setuptools==65.5.0 ; python_version >= "3.8" and python_version < "4.0"
six==1.16.0 ; python_version >= "3.8" and python_version < "4.0"
snowballstemmer==2.2.0 ; python_version >= "3.8" and python_version < "4.0"
soupsieve==2.3.2.post1 ; python_version >= "3.8" and python_version < "4.0"
sphinx-autobuild==2021.3.14 ; python_version >= "3.8" and python_version < "4.0"
sphinx-basic-ng==1.0.0b1 ; python_version >= "3.8" and python_version < "4.0"
sphinx-copybutton==0.5.0 ; python_version >= "3.8" and python_version < "4.0"
sphinx-intl==2.0.1 ; python_version >= "3.8" and python_version < "4.0"
sphinx-prompt==1.5.0 ; python_version >= "3.8" and python_version < "4.0"
sphinx-substitution-extensions==2022.2.16 ; python_version >= "3.8" and python_version < "4.0"
sphinx==5.3.0 ; python_version >= "3.8" and python_version < "4.0"
sphinxcontrib-applehelp==1.0.2 ; python_version >= "3.8" and python_version < "4.0"
sphinxcontrib-devhelp==1.0.2 ; python_version >= "3.8" and python_version < "4.0"
sphinxcontrib-htmlhelp==2.0.0 ; python_version >= "3.8" and python_version < "4.0"
sphinxcontrib-jsmath==1.0.1 ; python_version >= "3.8" and python_version < "4.0"
sphinxcontrib-qthelp==1.0.3 ; python_version >= "3.8" and python_version < "4.0"
sphinxcontrib-serializinghtml==1.1.5 ; python_version >= "3.8" and python_version < "4.0"
sphinxcontrib-towncrier==0.3.1a3 ; python_version >= "3.8" and python_version < "4.0"
tomli==2.0.1 ; python_version >= "3.8" and python_version < "4.0"
tornado==6.2 ; python_version >= "3.8" and python_version < "4.0"
towncrier==22.8.0 ; python_version >= "3.8" and python_version < "4.0"
typing-extensions==4.4.0 ; python_version >= "3.8" and python_version < "4.0"
urllib3==1.26.12 ; python_version >= "3.8" and python_version < "4"
uvloop==0.17.0 ; python_version >= "3.8" and python_version < "4.0" and sys_platform == "darwin" or python_version >= "3.8" and python_version < "4.0" and sys_platform == "linux"
wrapt==1.14.1 ; python_version >= "3.8" and python_version < "4.0"
yarl==1.8.1 ; python_version >= "3.8" and python_version < "4.0"
zipp==3.10.0 ; python_version >= "3.8" and python_version < "3.10"