// Этот файл создается с помощью .github/workflows/gh-pages.yml - все локальные изменения в конечном итоге будут потеряны! = ansible-role-pip Йонас Паммер opensource@jonaspammer.at; :toc: слева :toclevels: 2 :toc-placement!: :source-highlighter: rouge

https://galaxy.ansible.com/jonaspammer/pip[image:https://img.shields.io/badge/доступно%20на%20ansible%20galaxy-jonaspammer.pip-brightgreen[Версия на Galaxy]] // Очень важные статусные эмблемы https://github.com/JonasPammer/ansible-role-pip/actions/workflows/ci.yml[image:https://github.com/JonasPammer/ansible-role-pip/actions/workflows/ci.yml/badge.svg[Испытание CI]]

Ansible-роль для установки последней версии pip (установщика пакетов Python) в систему.

По умолчанию эта роль гарантирует, что версия pip всегда соответствует последней версии, которая работает с версией данного исполняемого файла Python (то, что просто pip --upgrade pip по какой-то причине не делает).

Эта роль также может быть использована для установки заданного набора пакетов pip как в систему, так и в виртуальном окружении.

toc::[]

[[meta]] == 🔎 Метаданные Ниже вы можете найти информацию о…

• необходимой версии Ansible для роли
• поддерживаемых платформах для роли
• зависимостях роли

.link:meta/main.yml[] [source,yaml]

---

---

galaxy_info: role_name: "pip" description: "Ansible-роль для установки последней версии pip (установщика пакетов Python) в систему."

author: "jonaspammer" license: "MIT"

min_ansible_version: "2.11" platforms: # примечание: текст после "активно тестируется: " представляет собой имя образа докера - name: EL # (Enterprise Linux) versions: - "9" # активно тестируется: rockylinux9 - name: Fedora versions: - "38" # активно тестируется: fedora38 - "39" # активно тестируется: fedora39 - name: Debian versions: - bullseye # активно тестируется: debian11 - bookworm # активно тестируется: debian12 - name: Ubuntu versions: - focal # активно тестируется: ubuntu2004 - jammy # активно тестируется: ubuntu2204

galaxy_tags: []

dependencies: []

[[requirements]] == 📌 Требования // Любые предпосылки, которые могут не охватываться этой ролью или самим Ansible, должны быть упомянуты здесь. Пользователь Ansible должен иметь возможность become.

Коллекция https://galaxy.ansible.com/community/general[`community.general`] должна быть установлена на контроллере Ansible.

[[variables]] == 📜 Переменные роли // Описание настраиваемых переменных для этой роли должно находиться здесь // и любые переменные, которые могут/должны быть установлены через параметры к роли. // Также должны быть упомянуты любые переменные, которые читаются из других ролей и/или глобальной области (например, hostvars, group vars и т. д.).

[source,yaml]

pip_version: [последняя возможная версия, которая поддерживает версию Python, указанную в pip_python_executable]

Версия pip для установки с использованием pip после того, как pip был установлен в виде https://pip.pypa.io/en/stable/cli/pip_install/#requirement-specifiers[спецификатора требований pip].

|=== | Версия за pip_python_executable | Значение pip_version

| несовпадение | >=22

| 3.6 | <22

| 3.5 или 2 (предположение о 2.7) | <21

| 3.4 | <19.2

| 3.3 | <18 |===

[TIP]

Посмотрите https://pypi.org/project/pip/#history[историю релизов pip] для доступных версий pip.

Также, если вам интересно, ознакомьтесь с https://pip.pypa.io/en/stable/news/[документацией pip] для общей записи изменений в проекте pip (Поддерживается, как описано в их https://pip.pypa.io/en/latest/development/contributing/#news-entries[Руководстве по взносам]).

[source,yaml]

pip_state: "forcereinstall"

Состояние, передаваемое в pip install pip. Одно из: forcereinstall, latest, present.

Если передается forcereinstall, эта роль пытается поддерживать идемпотентность, отключая changed_when при установке и вместо этого выполняя другую задачу, которая сравнивает результат до/после выполнения команды pip --version.

Если передается latest, значение pip_version не имеет эффекта.

[source,yaml]

pip_package: "python3-pip"

Имя пакета(ов), который(ые) необходимо установить для получения pip в системе. Для более старых систем, где Python 3 недоступен, вы можете установить это значение в python-pip.

[source,yaml]

pip_virtualenv_packages: [Специфично для ОС по умолчанию, см. директорию /defaults]

Имя пакета(ов), который(ые) необходимо установить для получения virtualenv в системе.

[source,yaml]

pip_executable: "{{ 'pip3' if pip_package.startswith('python3') else 'pip' }}"

pip_executable, переданный модулям ansible.builtin.pip, выдаваемым этой ролью.

Роль постарается автоматически определить исполняемый файл pip, основываясь на pip_package. Вы также можете явно переопределить это значение, например, pip_executable: pip3.6, если необходимо.

[source,yaml]

pip_install_packages: []

Список пакетов для установки с помощью https://docs.ansible.com/ansible/2.9/modules/pip_module.html[pip].

Каждая запись может быть либо простой строкой (краткий вариант для - name: …), либо отдельным объектом с нижеперечисленными свойствами:

chdir:: cd в этот каталог перед выполнением команды.

name:: Имя библиотеки Python для установки или URL(bzr+,hg+,git+,svn+) удаленного пакета.

version:: Номер версии, которую нужно установить для библиотеки Python, указанной в параметре name.

requirements:: Вместо использования name и version для определения одного пакета встроенным образом вы также можете использовать эту опцию, чтобы ссылаться на путь файла требований pip, который должен быть локальным для удаленной системы. Файл может быть указан как относительный путь, если используется опция chdir.

state:: Состояние модуля pip (т.е. отсутствие / forcereinstall / latest / present)

umask:: Устанавливается по умолчанию в pip_install_packages_umask, если он существует. + Системная маска, которая применяется перед установкой пакета pip. Это полезно, например, при установке на системах, где по умолчанию установлена очень строгая маска (например, "0077"), и вы хотите установить пакеты pip, которые будут использоваться всеми пользователями. Обратите внимание, что для этого необходимо указать желаемый режим маски в виде восьмеричной строки (например, "0022").

virtualenv:: Устанавливается по умолчанию в pip_install_packages_virtualenv, если он существует. + Путь к каталогу виртуального окружения для установки. Если виртуальное окружение не существует, оно будет создано до установки пакетов. Опциональные параметры virtualenv_command и virtualenv_python влияют на создание виртуального окружения.

virtualenv_command:: Устанавливается по умолчанию в pip_install_packages_virtualenv_command, если он существует. + Команда или путь к команде для создания виртуального окружения. Например, pyvenv, virtualenv, virtualenv2, ~/bin/virtualenv, /usr/local/bin/virtualenv.

virtualenv_python:: Устанавливается по умолчанию в pip_install_packages_virtualenv_python, если он существует. + Исполняемый файл Python, используемый для создания виртуального окружения. Например, python3.5, python2.7. Если не указано, используется версия Python, используемая для запуска модуля ansible. Этот параметр не следует использовать, когда команда virtualenv_command использует pyvenv или модуль -m venv.

virtualenv_site_packages:: Устанавливается по умолчанию в pip_install_packages_virtualenv_python, если он существует. + Будет ли виртуальное окружение наследовать пакеты из глобального каталога site-packages. Обратите внимание, что если эта настройка изменится после того, как виртуальное окружение уже существует, на него это не повлияет - окружение должно быть удалено и вновь создано.

extra_args:: Устанавливается по умолчанию в pip_install_packages_extra_args, если он существует. + Дополнительные аргументы, переданные pip.

environment:: Устанавливается по умолчанию в pip_install_packages_environment, если он существует. + Переменные окружения, переданные модулю pip.

[[pip_python_executable]] [source,yaml]

---

pip_python_executable: "{{ 'python3' if pip_package.startswith('python3') else 'python' }}"

Эта переменная используется для определения значения по умолчанию для pip_version.

Роль попытается автоматически определить исполняемый файл Python на основе pip_package.

[[public_vars]] == 📜 Факты/переменные, определяемые этой ролью

Каждая переменная, перечисленная в этом разделе, динамически определяется при выполнении этой роли (и может быть переопределена только с помощью ansible.builtin.set_facts) и предназначена для использования не только внутри роли.

[[tags]] == 🏷️ Теги

// Ознакомьтесь с https://github.com/tribe29/ansible-collection-tribe29.checkmk/blob/main/roles/server/README.md#tags // для отличного примера группировки задач с использованием тегов

Задачи помечены следующими https://docs.ansible.com/ansible/latest/user_guide/playbooks_tags.html#adding-tags-to-roles[тегами]:

[cols="1,1"] |=== |Тег | Цель

2+| Эта роль еще не имеет официально задокументированных тегов. // | download-xyz // | // | install-prerequisites // | // | install // | // | create-xyz // | |===

Вы можете использовать Ansible, чтобы пропустить задачи или запустить только определенные задачи, используя эти теги. По умолчанию выполняются все задачи, когда теги не указаны.

[[dependencies]] == 👫 Зависимости // Список других ролей должен находиться здесь, // плюс любые детали, касающиеся параметров, которые могут потребоваться для установки других ролей, // или переменных, которые используются из других ролей.

[[example_playbooks]] == 📚 Примеры использования плейбуков // Включение примеров того, как использовать эту роль в плейбуке для распространенных сценариев, всегда полезно для пользователей.

[NOTE]

Эта роль является частью https://github.com/JonasPammer/ansible-roles[многих совместимых ролей, созданных для конкретных целей].

Машина должна быть подготовлена. В CI это делается в molecule/default/prepare.yml, который получает свои зависимости из requirements.yml:

.link:molecule/resources/prepare.yml[] [source,yaml]

---

---

• name: prepare hosts: all become: true gather_facts: false

  roles:

  • role: jonaspammer.bootstrap

  - role: jonaspammer.core_dependencies

---

Следующая диаграмма является сборкой "мягких зависимостей" этой роли, а также рекурсивным деревом их мягких зависимостей.

image:https://raw.githubusercontent.com/JonasPammer/ansible-roles/master/graphs/dependencies_pip.svg[граф зависимостей requirements.yml для jonaspammer.pip]

. Минимально жизнеспособный Play

[source,yaml]

---

roles:

• role: jonaspammer.pip

---

====

. Установка pip для Python 2

[source,yaml]

---

roles:

• role: jonaspammer.pip

vars:

• pip_package: "python-pip"

---

====

. Установка пакетов pip

[source,yaml]

---

roles:

• role: jonaspammer.pip

vars: pip_install_packages:

Укажите имена и версии.

• name: docker version: "1.2.3"
• name: awscli version: "1.11.91"

Или укажите простые пакеты, чтобы получить последнюю версию (при первой установке).

• docker
• awscli

Или удалите пакет.

• name: docker state: absent

Или обновите пакет до последней версии.

• name: docker state: latest

Или принудительно переустановите.

• name: docker state: forcereinstall

---

====

[[tested-distributions]] == 🧪 Проверенные дистрибутивы

Роль может работать на различных дистрибутивах, таких как Red Hat Enterprise Linux (RHEL), даже если для этого конкретного дистрибутива нет теста.

// хорошая ссылка на то, что нужно следовать -- самый звездный и закрепленный проект geerlingguy: // https://github.com/geerlingguy/ansible-role-docker/blob/master/.github/workflows/ci.yml |=== | Семейство ОС | Дистрибутив | Дата выпуска дистрибутива | Дата окончания поддержки дистрибутива | Сопровождающий образ Docker

// https://endoflife.date/rocky-linux | Rocky | Rocky Linux 8 (https://www.howtogeek.com/devops/is-rocky-linux-the-new-centos/[RHEL/CentOS 8 под другим именем]) | 2021-06 | 2029-05 | https://github.com/geerlingguy/docker-rockylinux8-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-rockylinux8-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Rocky | Rocky Linux 9 | 2022-07 | 2032-05 | https://github.com/geerlingguy/docker-rockylinux9-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-rockylinux9-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://endoflife.date/fedora (13 месяцев) | RedHat | Fedora 39 | 2023-11 | 2024-12 | https://github.com/geerlingguy/docker-fedora39-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-fedora39-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://ubuntu.com/about/release-cycle | Debian | Ubuntu 20.04 LTS | 2021-04 | 2025-04 | https://github.com/geerlingguy/docker-ubuntu2004-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-ubuntu2004-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian | Ubuntu 22.04 LTS | 2022-04 | 2027-04 | https://github.com/geerlingguy/docker-ubuntu2204-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-ubuntu2204-ansible/workflows/Build/badge.svg?branch=master[CI]]

// https://wiki.debian.org/DebianReleases // https://wiki.debian.org/LTS | Debian | Debian 11 | 2021-08 | 2024-06 (2026-06 LTS) | https://github.com/geerlingguy/docker-debian11-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-debian11-ansible/workflows/Build/badge.svg?branch=master[CI]]

| Debian | Debian 12 | 2023-06 | 2026-06 (2028-06 LTS) | https://github.com/geerlingguy/docker-debian12-ansible/actions?query=workflow%3ABuild[image:https://github.com/geerlingguy/docker-debian12-ansible/workflows/Build/badge.svg?branch=master[CI]] |===

[[tested-ansible-versions]] == 🧪 Проверенные версии Ansible

Проверенные версии ansible стремятся оставаться эквивалентными поддерживаемым версиям https://github.com/ansible-collections/community.general#tested-with-ansible[коллекции community.general Ansible]. На момент написания это:

• 2.13 (Ansible 6)
• 2.14 (Ansible 7)
• 2.15 (Ansible 8)
• 2.16 (Ansible 9)

[[development]] == 📝 Разработка // Значки о Конвенциях в этом Проекте https://conventionalcommits.org[image:https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg[Конвенциональные Коммиты]] https://results.pre-commit.ci/latest/github/JonasPammer/ansible-role-pip/master[image:https://results.pre-commit.ci/badge/github/JonasPammer/ansible-role-pip/master.svg[статус pre-commit]] // image:https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white[pre-commit, link=https://github.com/pre-commit/pre-commit]

[[development-system-dependencies]] === 📌 Зависимости системы для разработки

• Python 3.10 или выше
• Docker

[[development-dependencies]] === 📌 Зависимости для разработки Зависимости для разработки определяются в https://pip.pypa.io/en/stable/user_guide/#requirements-files[файле требований pip], названном requirements-dev.txt. Пример инструкции по установке для Linux приведен ниже:

---

"опционально": создайте виртуальное окружение python и активируйте его для текущей сессии оболочки

$ python3 -m venv venv $ source venv/bin/activate

$ python3 -m pip install -r requirements-dev.txt

[[development-guidelines]] === ℹ️ Руководство по разработке ролей Ansible

Пожалуйста, ознакомьтесь с моим https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_GUIDELINES.adoc[Руководством по Разработке Ролей Ansible].

Если вам интересно, я также изложил некоторые https://github.com/JonasPammer/cookiecutter-ansible-role/blob/master/ROLE_DEVELOPMENT_TIPS.adoc[Лучшие Практики Разработки Ролей Ansible].

[[versioning]] === 🔢 Версионирование

Версии определяются с использованием https://git-scm.com/book/en/v2/Git-Basics-Tagging[Тэгов], которые, в свою очередь, https://galaxy.ansible.com/docs/contributing/version.html[признаются и используются] Ansible Galaxy.

Версии не должны начинаться с v.

Когда новый тег отправляется, https://github.com/JonasPammer/ansible-role-pip/actions/workflows/release-to-galaxy.yml[работа GitHub CI] (image:https://github.com/JonasPammer/ansible-role-pip/actions/workflows/release-to-galaxy.yml/badge.svg[Выпуск CI]) отвечает за импорт роли в мой аккаунт Ansible Galaxy.

[[testing]] === 🧪 Тестирование Автоматические тесты запускаются на каждом внесении изменений с использованием GitHub Workflows.

Тесты в основном касаются выполнения https://molecule.readthedocs.io/en/latest/[Molecule] на <<tested-distributions,разных дистрибутивах linux>> и использования <<tested-ansible-versions,различных версий ansible>>.

Тест Molecule также включает шаг, который проверяет все плейбуки ansible с помощью https://github.com/ansible/ansible-lint#readme[`ansible-lint`] для проверки соблюдения лучших практик и поведения, которое потенциально можно улучшить.

Для запуска тестов просто выполните tox в командной строке. Вы можете передать необязательную переменную окружения, чтобы определить дистрибутив контейнера Docker, который будет запущен с помощью Molecule:

---

$ MOLECULE_DISTRO=ubuntu2204 tox

Для получения списка возможных значений, передаваемых MOLECULE_DISTRO, ознакомьтесь с матрицей, определенной в link:.github/workflows/ci.yml[].

==== 🐛 Отладка контейнера Molecule

1. Запустите ваши тесты Molecule с опцией MOLECULE_DESTROY=never, например:

• [subs="quotes,macros"]

---

$ MOLECULE_DESTROY=never MOLECULE_DISTRO=#ubuntu1604# tox -e py3-ansible-#5# ... TASK [ansible-role-pip : (проверка).] pass:[************************] failed: [instance-py3-ansible-9] => changed=false ... pass:[___________________________________ summary ____________________________________] pre-commit: команды выполнены успешно ERROR: py3-ansible-9: команды не выполнены

---

2. Узнайте имя контейнера докера, созданного molecule:

• [subs="quotes"]

---

$ docker ps #30e9b8d59cdf# geerlingguy/docker-debian12-ansible:latest "/lib/systemd/systemd" 8 минут назад Запущен 8 минут instance-py3-ansible-9

---

3. Зайдите в оболочку bash контейнера и проведите отладку:

• [subs="quotes"]

---

$ docker exec -it #30e9b8d59cdf# /bin/bash

root@instance-py3-ansible-2:/#

• [TIP]

  Если ошибка, которую вы пытаетесь отладить, является частью вашего шага verify.yml, а не фактического converge.yml, вам может быть важно знать, что выходные данные модулей ansible (vars), хостов (hostvars) и переменных окружения были сохранены в файлы как на провизионере, так и внутри докер-машины, в следующих директориях:

• /var/tmp/vars.yml (содержит переменные хоста под ключом hostvars)
• /var/tmp/environment.yml

  grep, cat или передавайте эти файлы по мере необходимости!

• [TIP]

  Также вам может быть интересно знать, что файлы, упомянутые в приведенном выше уведомлении, прикреплены к Артефактам CI GitHub определенного выполнения рабочего процесса. + Это позволяет проверить разницу между запусками и, таким образом, помочь в отладке причин, вызвавших ошибку или сбой.

image::https://user-images.githubusercontent.com/32995541/178442403-e15264ca-433a-4bc7-95db-cfadb573db3c.png[]

4. После того как вы закончите отладку, выйдите и уничтожьте контейнер:

• [subs="quotes"]

---

root@instance-py3-ansible-2:/# exit

$ docker stop #30e9b8d59cdf#

$ docker container rm #30e9b8d59cdf# или $ docker container prune

---

==== 🐛 Отладка установленных версий пакетов локально

Хотя это стандартная функция в tox 3, https://github.com/tox-dev/tox/pull/2794[сейчас] это происходит только тогда, когда tox распознает наличие переменной CI. Например:

---

$ CI=true tox

[[development-container-extra]] === 🧃 TIP: Идеальная Контейнеризированная Среда для Разработки

Этот проект предлагает определение для "Контейнеризированной Среды для Разработки с одной кнопкой".

Этот контейнер даже позволяет запускать внутри себя контейнеры Docker (Docker-In-Docker, dind), что позволяет выполнять molecule.

Для использования:

1. Убедитесь, что вы соответствуете ссылке на https://code.visualstudio.com/docs/remote/containers#_system-requirements[системные требования контейнеров разработки Visual Studio Code], возможно, следуя разделу Установка на указанной странице. + Это включает: установку Docker, установку самого Visual Studio Code и установку необходимого расширения.
2. Клонируйте проект на свой компьютер
3. Откройте папку репозитория в Visual Studio Code (Файл - Открыть папку…).
4. Если вы получите подсказку в правом нижнем углу о наличии определения devcontainer, вы можете нажать соответствующую кнопку, чтобы войти в него. В противном случае вы также можете выполнить команду Visual Studio Remote-Containers: Open Folder in Container самостоятельно (Просмотр - Командная панель -> введите указанную команду).

[TIP]

Рекомендую использовать Remote-Containers: Rebuild Without Cache and Reopen in Container время от времени, так как функция devcontainer иногда имеет проблемы с корректным распознаванием изменений, внесенных в его определение.

[NOTE]

Возможно, вам потребуется настроить вашу хост-систему, чтобы разрешить контейнеру использовать ваши SSH/GPG ключи.

Процедура описана в https://code.visualstudio.com/remote/advancedcontainers/sharing-git-credentials[официальной документации devcontainer в разделе "Совместное использование учетных данных Git с вашим контейнером"].

[[cookiecutter]] === 🍪 CookieCutter

Этот проект должен быть синхронизирован с https://github.com/JonasPammer/cookiecutter-ansible-role[CookieCutter, из которого он изначально был создан], используя https://github.com/cruft/cruft[cruft] (если это возможно) или ручные изменения (если это необходимо) в максимально возможной мере.

. Официальный пример использования cruft update

---

image::https://raw.githubusercontent.com/cruft/cruft/master/art/example_update.gif[Официальный пример использования cruft update]

---

==== 🕗 Журнал изменений Когда новый тег отправляется, соответствующий релиз GitHub будет создан наставником репозитория, чтобы предоставить правильный журнал изменений с названием и описанием.

[[pre-commit]] === ℹ️ Общие Конвенции по Линтингу и Стилю Общие Конвенции по Линтингу и Стилю https://stackoverflow.blog/2020/07/20/linters-arent-in-your-way-theyre-on-your-side/[*автоматически* поддерживаются стандартам] различными https://pre-commit.com/[`pre-commit`] хуками, по крайней мере, частично.

Автоматическое выполнение pre-commit происходит на каждом внесении изменений с использованием https://pre-commit.ci/[`pre-commit.ci`]<<note_pre-commit-ci,*>>. Запросы на вливание даже автоматически исправляются тем же инструментом, по крайней мере, хуками, которые автоматически изменяют файлы.

[NOTE]

Не путайте: Хотя некоторые хуки pre-commit могут быть способны предупредить вас о проблемах с синтаксисом или даже кодом до некоторой степени (по этой причине хуки pre-commit являются частью тестового набора), сам pre-commit не запускает настоящие тестовые наборы. Для получения информации о тестировании смотрите <>. ====

[TIP]

[[note_pre-commit-ci]] Тем не менее, я рекомендую вам интегрировать pre-commit в свой локальный рабочий процесс разработки самостоятельно.

Это можно сделать, перейдя в каталог вашего клонированного проекта и запустив pre-commit install. Сделав это, git будет запускать проверки pre-commit при каждом вашем коммите, отменяя сам коммит, если сработает какой-либо хук.

Вы также можете, например, выполнить хуки pre-commit в любое время, запустив pre-commit run --all-files.

[[contributing]] == 💪 Вклад https://open.vscode.dev/JonasPammer/ansible-role-pip[image:https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc[Открыть в Visual Studio Code]] image:https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square[Приветствуются PR]

// Включено в README.adoc :toc: :toclevels: 3

Следующие разделы являются общими по своему характеру и предназначены для помощи новым участникам. Фактическая "Документация по Разработке" этого проекта находится в разделе <>.

=== 🤝 Введение Прежде всего, спасибо, что рассматриваете возможность внести вклад в этот проект.

Соблюдение этих рекомендаций показывает, что вы уважаете время разработчиков, управляющих и развивающих этот проект с открытым исходным кодом. В свою очередь, они должны ответить вам уважением, рассматривая вашу проблему, оценивая изменения и помогая вам завершить ваши запросы на вливание.

[[cookiecutter--contributing]] === 🍪 CookieCutter Этот проект обязан многими своими файлами https://github.com/JonasPammer/cookiecutter-ansible-role[CookieCutter, из которого он изначально был создан].

Пожалуйста, проверьте, является ли изменение, которое вы имеете в виду, действительно применимым к шаблону, и если это так, произведите соответствующее изменение там. Ваше изменение также может быть частично применимо к шаблону, а частично к чему-то конкретному для этого проекта, в таком случае вы создадите несколько PR.

=== 💬 Конвенционные Коммиты

Обычному участнику не нужно беспокоиться о соблюдении https://github.com/JonasPammer/JonasPammer/blob/master/demystifying/conventional_commits.adoc[__спецификации__] https://www.conventionalcommits.org/en/v1.0.0/[__по определению__], так как запросы на вливание объединяются в один коммит в проекте. Только основные участники, т.е. те, кто имеют права на внесение изменений в ветки этого проекта, должны следовать этим правилам (например, чтобы автоматическое определение версий и генерация журнала изменений работали).

=== 🚀 Начало работы

Вклады в этот репозиторий делаются через Issues и Pull Requests (PR). Несколько общих рекомендаций, которые касаются обоих:

• Перед созданием своей собственной проблемы ищите существующие Issues и PR.
• Если вы никогда не делали взносов раньше, посмотрите https://auth0.com/blog/a-first-timers-guide-to-an-open-source-project/[руководство для новичков на блоге Auth0] для получения ресурсов и советов о том, как начать.

==== Issues

Проблемы должны использоваться для сообщения о проблемах, запроса новой функции или обсуждения потенциальных изменений до создания PR. Когда вы https://github.com/JonasPammer/ansible-role-pip/issues/new[создаете новую проблему], будет загружен шаблон, который поможет вам собрать и предоставить информацию, необходимую для расследования.

Если вы найдете проблему, касающуюся вашей проблемы, пожалуйста, добавьте информацию о воспроизведении к существующей проблеме вместо того, чтобы создавать новую. Добавление реакции https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/[может также помочь, указывая нашим сопровождающим, что конкретная проблема затрагивает больше, чем просто сообщающий].

==== Pull Requests

PR в этот проект всегда приветствуются и могут быть быстрым способом зафиксировать ваш фикс или улучшение для следующего релиза. https://blog.ploeh.dk/2015/01/15/10-tips-for-better-pull-requests/[В общем] PR должны:

• Исправить/добавить только необходимую функциональность ИЛИ касаться широко распространенных проблем стиля/отступов, а не обоих.
• Добавить модульные или интеграционные тесты для исправленной или измененной функциональности (если уже существует тестовый набор).
• Касаться одной проблемы
• Включать документацию в репозиторий
• Сопровождаться полным шаблоном Pull Request (загружается автоматически при создании PR).

Для изменений, которые затрагивают основную функциональность или потребуют разрывных изменений (например, мажорный релиз), лучше сначала открыть Issue, чтобы обсудить ваше предложение.

В общем, мы следуем "ветвить-и-вливать" рабочему процессу Git:

1. Ветвите репозиторий в свой собственный аккаунт Github
2. Клонируйте проект на свой компьютер
3. Создайте локально ветку с кратким, но описательным названием
4. Закоммитьте изменения на этой ветке
5. Следуя любым специфическим руководствам по форматированию и тестированию для этого репозитория
6. Запушьте изменения в свой форк
7. Откройте PR в нашем репозитории и следуйте шаблону PR, чтобы мы могли эффективно просмотреть изменения.

[[changelog]] == 🗒 Журнал изменений Пожалуйста, смотрите на https://github.com/JonasPammer/ansible-role-pip/releases[страницу релизов этого репозитория] для получения человеческого журнала изменений, соответствующего https://github.com/JonasPammer/ansible-role-pip/tags[тэгам (версиям) этого проекта].

Обратите внимание, что этот проект придерживается семантического версионирования. Пожалуйста, сообщайте о любых случайных разрывных изменениях в обновлении минорной версии.

[[license]] == ⚖️ Лицензия

.link:LICENSE[]

MIT License

Copyright (c) 2022, Йонас Паммер

Настоящим предоставляется разрешение, безвозмездно, любому лицу, получающему копию данного программного обеспечения и сопутствующей документации (далее именуемого "Программное обеспечение"), использовать Программное обеспечение без ограничений, включая, помимо прочего, права использовать, копировать, изменять, объединять, публиковать, распространять, предоставлять сублицензии и/или продавать копии Программного обеспечения, а также разрешать лицам, которым Программное обеспечение предоставлено, делать это, при соблюдении следующих условий:

Указанное выше уведомление об авторском праве и это уведомление о разрешении должны быть включены во все копии или значительные части Программного обеспечения.

ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ ГАРАНТИЙ ЛЮБОГО РОДА, ЯВНЫХ ИЛИ НЕЯВНЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ГАРАНТИЯМИ ПРОДАЖИ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И ОТРИЦАНИЯ. В НИКАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ВЛАДЕЛЬЦЫ АВТОРСКИХ ПРАВ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ИСКИ, УЩЕРБ ИЛИ ИНЫЕ ОБЯЗАТЕЛЬСТВА, БУДУЩИЕ ИЛИ ИНЫЕ, В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ АБО ИНЫМИ ДИАНТАРАМИ В ПРОГРАММНОМ ОБЕСПЕЧЕНИИ.

---