XlsxWriter: Отчеты о багах и Pull Requests

Отчет о багах

Вот несколько советов по отчету о багах в XlsxWriter.

Обновление до последней версии модуля

Баг, который вы отслеживаете, может быть уже исправлен в последней версии модуля. Вы можете проверить, какая версия xlsxwriter используется следующим образом:

python -c "import xlsxwriter; print(xlsxwriter.__version__)"

Файл Changes содержит информацию о том, что изменилось в последних версиях.

Чтение документации

Прочитайте или поищите документацию XlsxWriter для проверки, не объясняется ли уже ваша проблема.

Посмотрите примерные программы

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

Указания по отправке отчета о баге

1. Опишите проблему как можно более ясно и кратко.
2. Включите примерную программу. Это, вероятно, самый важный шаг. Обычно проще описать проблему с помощью кода, чем с помощью письменного текста.
3. Примерная программа должна быть как можно меньше для демонстрации проблемы. Не копируйте и не вставляйте большие несвязанные с проблемой части вашего кода.

Пример отчета о баге

Пример отчета о баге приведен ниже. Этот формат помогает быстрее анализировать и отвечать на отчет о баге.

Проблема с SOMETHING

Я использую XlsxWriter для выполнения SOMETHING, но кажется, что он выполняет SOMETHING ELSE.

Я использую Python версии X.Y.Z и XlsxWriter x.y.z.

Вот пример кода, демонстрирующий проблему:

  import xlsxwriter

  workbook = xlsxwriter.Workbook('hello.xlsx')
  worksheet = workbook.add_worksheet()

  worksheet.write('A1', 'Hello world')

  workbook.close()

См. также, как создать минимальный, полный и проверяемый пример на StackOverflow.

Используйте XlsxWriter GitHub issue tracker

Отправьте отчет о баге с помощью XlsxWriter issue tracker.

Pull Requests и вклад в XlsxWriter

Все патчи и pull requests приветствуются, но должны начинаться с issue tracker.### Начало работы

1. Запросы на внесение изменений и предложения новых функций должны начинаться с системы отслеживания проблем. Это служит центром обсуждения дизайна.
2. Опишите, что вы планируете сделать. Если есть изменения или добавления в API, добавьте псевдокод для демонстрации этих изменений.
3. Создайте форк репозитория.
4. Запустите все тесты, чтобы убедиться, что текущий код работает на вашей системе, используя make test.
5. Создайте ветку для новой функции.

Написание тестов

Это самый важный шаг. XlsxWriter имеет более 1000 тестов и соотношение 2:1 между тестами и кодом. Патчи и запросы на внесение изменений для чего-либо, кроме небольших исправлений или опечаток, не будут приняты без тестов. Используйте существующие тесты в XlsxWriter/xlsxwriter/test/ в качестве примеров.

Идеально, новые функции должны сопровождаться тестами, которые сравнивают выходные данные XlsxWriter с реальными файлами Excel 2007. См. тестовые файлы в XlsxWriter/xlsxwriter/test/comparison для примеров. Если у вас нет доступа к Excel 2007, я могу помочь вам создать входные файлы для тестовых случаев.

Тесты должны использовать стандартный модуль unittest Python.

Стиль кода

Следуйте общему стилю окружающего кода и форматируйте его в соответствии со стандартами PEP8.

Тесты должны соответствовать PEP8, но могут игнорировать E501 для длинных строк для включения Excel XML в тестах.

Существует цель make, которая будет проверять исходные и тестовые файлы с помощью flake8:

make test_flake8

Запуск тестов

Как минимум, тесты должны запускаться с использованием Python 3.6+.

make test
# или
pytest

Когда вы отправите свои изменения, они также будут тестироваться с помощью GitHub Actions.

Документация

Если ваша функция требует этого, напишите некоторую RST документацию в формате Sphinx или добавьте к существующей документации.

Документация, находящаяся в dev/docs/source, может быть построена в формате Html с помощью:

make docs### Примерные программы

Если применимо, добавьте примерную программу в директорию examples.

Авторское право и лицензия

Авторское право остаётся у оригинального автора. Не включайте дополнительные утверждения об авторском праве или требования к лицензии. GitHub и репозиторий git будут фиксировать ваш вклад, и он будет упомянут в файле Changes.

Отправка pull запроса

Если ваша правка включает несколько последовательных коммитов git, используйте rebase или squash, чтобы объединить их в одну ветку, чтобы pull запрос состоял из одного коммита или небольшого числа логически связанных коммитов.

Отправьте ваши изменения на GitHub и создайте pull запрос с ссылкой на задачу в Issue трекере, открытую выше.