diff --git a/.readthedocs.yml b/.readthedocs.yml index 8fbc4dc1..56287c32 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -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 diff --git a/CHANGES/1095.misc.rst b/CHANGES/1095.misc.rst index 5a9f5bbb..87de48c8 100644 --- a/CHANGES/1095.misc.rst +++ b/CHANGES/1095.misc.rst @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ada02324 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +Please read the [Contributing](https://docs.aiogram.dev/en/dev-3.x/contributing/) guidelines in the documentation site. diff --git a/Makefile b/Makefile index dfdca2f1..cbe5c333 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..80709756 --- /dev/null +++ b/docs/contributing.rst @@ -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 `_ + +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://:/ 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 + +Change the :code:`` in example below to the target language code, after that +you can modify texts inside :code:`docs/locale//LC_MESSAGES` as :code:`*.po` files +by using any text-editor or specialized utilites for GNU Gettext, +for example via `poedit `_. + +To view results: + +.. code-block:: bash + + sphinx-autobuild --watch aiogram/ docs/ docs/_build/ -D language= + + +Describe changes +---------------- + +Describe your changes in one or more sentences so that bot developers know what's changed +in their favorite framework - create `..rst` file and write the description. + +:code:`` is Issue or Pull-request number, after release link to this issue will +be published to the *Changelog* page. + +:code:`` 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 `_) 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 `_ +or `Patreon `_. diff --git a/docs/index.rst b/docs/index.rst index 2d007e88..d6ffb067 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,3 +16,4 @@ Contents dispatcher/index utils/index changelog + contributing diff --git a/requirements/base.txt b/requirements/base.txt deleted file mode 100644 index 3bd59183..00000000 --- a/requirements/base.txt +++ /dev/null @@ -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" diff --git a/requirements/docs.txt b/requirements/docs.txt deleted file mode 100644 index 9cb54aec..00000000 --- a/requirements/docs.txt +++ /dev/null @@ -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"