Руководство по участию

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

Ограничения

При разработке следует придерживаться следующих пунктов:

Некоторые компании до сих пор используют старые версии Spark, например 2.3.1. Поэтому, по возможности, необходимо сохранять совместимость, например, добавлять ветки для разных версий Spark.
Разные пользователи используют onETL по-разному - некоторые используют только DB коннекторы, некоторые только файлы. Зависимости, специфичные для коннекторов, должны быть необязательными.
Вместо создания классов с большим количеством различных опций, лучше разделить их на более мелкие классы, например, класс опций, контекстный менеджер и т.д., и использовать композицию.

Начальная настройка для локальной разработки

Установите Git

Пожалуйста, следуйте инструкции.

Создайте форк

Если вы не являетесь членом команды разработчиков, создающей onETL, вам следует создать форк, прежде чем вносить какие-либо изменения.

Пожалуйста, следуйте инструкции.

Клонируйте репозиторий

Откройте терминал и выполните следующие команды:

git clone git@github.com:myuser/onetl.git -b develop

cd onetl

Включите pre-commit hooks

Установите pre-commit hooks:

pre-commit install --install-hooks

Проверьте запуск pre-commit hooks:

pre-commit run

Как тестировать

Запустите тесты локально

Note

You can skip this if only documentation is changed.

Используя docker-compose

Соберите образ для запуска тестов:

docker-compose build

Запустите все контейнеры с зависимостями:

docker-compose --profile all up -d

Вы можете запустить ограниченный набор зависимостей:

docker-compose --profile mongodb up -d

Запустите тесты:

docker-compose run --rm onetl ./run_tests.sh

Вы можете передать дополнительные аргументы, они будут переданы в pytest:

docker-compose run --rm onetl ./run_tests.sh -m mongodb -lsx -vvvv --log-cli-level=INFO

Вы можете запустить интерактивную bash сессию и использовать ее:

docker-compose run --rm onetl bash

./run_tests.sh -m mongodb -lsx -vvvv --log-cli-level=INFO

Посмотрите логи тестового контейнера:

docker-compose logs -f onetl

Остановите все контейнеры и удалите созданные тома:

docker-compose --profile all down -v

Без docker-compose

Warning

Для локального запуска тестов HDFS необходимо добавить следующую строку в файл /etc/hosts (путь к файлу зависит от ОС):

# HDFS server returns container hostname as connection address, causing error in DNS resolution
127.0.0.1 hdfs

Note

Для запуска тестов Oracle необходимо установить Oracle instantclient и передать его путь в переменные окружения ONETL_ORA_CLIENT_PATH и LD_LIBRARY_PATH, например, ONETL_ORA_CLIENT_PATH=/path/to/client64/lib.

Также может потребоваться добавить тот же путь в переменную окружения LD_LIBRARY_PATH.

Note

Для запуска тестов Greenplum необходимо:

Скачать [VMware Greenplum connector for Spark][DB-ONETL-doc-connection-db-connection-greenplum-prerequisites]
Либо переместить его в ~/.ivy2/jars/, либо передать путь к файлу в CLASSPATH
Установить переменную окружения ONETL_GP_PACKAGE_VERSION=local.

Запустите все контейнеры с зависимостями:

docker-compose --profile all up -d

Вы можете запустить ограниченный набор зависимостей:

docker-compose --profile mongodb up -d

Загрузите переменные окружения со свойствами подключения:

source .env.local

Запустите тесты:

./run_tests.sh

Вы можете передать дополнительные аргументы, они будут переданы в pytest:

./run_tests.sh -m mongodb -lsx -vvvv --log-cli-level=INFO

Остановите все контейнеры и удалите созданные тома:

docker-compose --profile all down -v

Соберите документацию

Note

You can skip this if only source code behavior remains the same.

Create virtualenv and install dependencies:

make venv-install

Соберите документацию с помощью Sphinx:

cd docs
make html

Затем откройте в браузере docs/_build/index.html.

Процесс рецензирования

Пожалуйста, создайте новую задачу GitHub для любых значительных изменений и улучшений, которые вы хотите внести. Укажите функцию, которую вы хотели бы видеть, зачем она вам нужна и как она будет работать. Обсуждайте свои идеи открыто и получайте отзывы сообщества, прежде чем продолжить.

Значительные изменения, которые вы хотите внести в проект, следует сначала обсудить в задаче GitHub, в которой четко изложены изменения и преимущества этой функции.

Небольшие изменения можно сразу же создать и отправить в репозиторий GitHub в виде запроса на включение (Pull Request).

Создайте pull request

Зафиксируйте свои изменения:

git commit -m "Commit message"
git push

Затем откройте интерфейс Github и создайте pull request. Пожалуйста, следуйте руководству из шаблона тела PR.

После создания pull request он получает соответствующий номер, например, 123 (pr_number).

Напишите release notes

onETL использует towncrier для управления журналом изменений.

Чтобы отправить заметку об изменении для вашего PR, добавьте текстовый файл в папку docs/changelog/next_release. Он должен содержать объяснение того, как применение этого PR изменит способ взаимодействия конечных пользователей с проектом. Одного предложения обычно достаточно, но не стесняйтесь добавлять столько деталей, сколько считаете необходимым для того, чтобы пользователи поняли, что это значит.

Используйте прошедшее время для текста в вашем фрагменте, потому что, в сочетании с другими, он будет частью "сводки новостей", рассказывающей читателям что изменилось в конкретной версии библиотеки с момента предыдущей версии.

Вам также следует использовать синтаксис reStructuredText для выделения кода (встроенного или блочного), связывания частей документации или внешних сайтов. Если вы хотите подписать свое изменение, не стесняйтесь добавить -- by :user:github-username` в конце (заменитеgithub-username` на свой собственный!).

Наконец, назовите свой файл в соответствии с соглашением, которое понимает Towncrier: он должен начинаться с номера задачи или PR, за которым следует точка, затем добавьте тип патча, например, feature, doc, misc и т.д., и добавьте .rst в качестве суффикса. Если вам нужно добавить более одного фрагмента, вы можете добавить необязательный порядковый номер (разделенный другой точкой) между типом и суффиксом.

В общем, имя будет соответствовать шаблону <pr_number>.<category>.rst, где категории:

feature: Любая новая функция
bugfix: Исправление ошибки
improvement: Улучшение
doc: Изменение в документации
dependency: Изменения, связанные с зависимостями
misc: Внутренние изменения в репозитории, такие как CI, тесты и изменения сборки

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

Примеры добавления записей в журнал изменений в ваши Pull Requests

Added a ``:github:user:`` role to Sphinx config -- by :github:user:`someuser`

Fixed behavior of ``WebDAV`` connector -- by :github:user:`someuser`

Added support of ``timeout`` in ``S3`` connector
-- by :github:user:`someuser`, :github:user:`anotheruser` and :github:user:`otheruser`

Как пропустить проверку заметок об изменениях?

Просто добавьте метку ci:skip-changelog к pull request.

Tip

See pyproject.toml for all available categories (tool.towncrier.type).

Процесс релиза

Note

This is for repo maintainers only

Перед тем, как сделать релиз из ветки develop, выполните следующие шаги:

Перейдите в ветку develop и обновите ее до актуального состояния
```
git checkout develop
git pull -p
```

Сделайте резервную копию NEXT_RELEASE.rst

cp "docs/changelog/NEXT_RELEASE.rst" "docs/changelog/temp_NEXT_RELEASE.rst"

Соберите Release notes с помощью Towncrier

VERSION=$(cat onetl/VERSION)
towncrier build "--version=${VERSION}" --yes

Измените файл с журналом изменений на номер версии релиза
```
mv docs/changelog/NEXT_RELEASE.rst "docs/changelog/${VERSION}.rst"
```

Удалите содержимое над заголовком номера версии в файле ${VERSION}.rst

awk '!/^.*towncrier release notes start/' "docs/changelog/${VERSION}.rst" > temp && mv temp "docs/changelog/${VERSION}.rst"

Обновите индекс журнала изменений

awk -v version=${VERSION} '/DRAFT/{print;print "    " version;next}1' docs/changelog/index.rst > temp && mv temp docs/changelog/    index.rst

Восстановите файл NEXT_RELEASE.rst из резервной копии
```
mv "docs/changelog/temp_NEXT_RELEASE.rst" "docs/changelog/NEXT_RELEASE.rst"
```
Зафиксируйте и отправьте изменения в ветку develop
```
git add .
git commit -m "Prepare for release ${VERSION}"
git push
```

Слейте ветку develop в master, БЕЗ squashing

git checkout master
git pull
git merge develop
git push

Добавьте git tag к последнему коммиту в ветке master
```
git tag "$VERSION"
git push origin "$VERSION"
```

Обновите версию в ветке develop после релиза:

git checkout develop

NEXT_VERSION=$(echo "$VERSION" | awk -F. '/[0-9]+\./{$NF++;print}' OFS=.)
echo "$NEXT_VERSION" > onetl/VERSION

git add .
git commit -m "Bump version"
git push