Как внести свой вклад

Здравствуйте! Благодарим вас за желание внести свой вклад в проект Awesome Python Applications! Ваша помощь очень важна для того, чтобы сделать APA лучшим проектом.

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

Добавление проекта

Прежде всего убедитесь, что проект ещё не внесён в список, а также что его нет в списках «TODO», «архив» и «пересмотр». Мы рассмотрели тысячи проектов, так что шансы, что он уже есть, неплохие.

Простой способ

Самый простой способ добавить проект — это создать заявку, используя шаблон заявки. Администратор рассмотрит её и добавит проект, следуя весёлому стандартному процессу, описанному ниже.

Весёлый способ

APA структурирован вокруг файла YAML projects.yaml, который используется для проверки и создания различных списков, включая RSS-канал. Для рендеринга документов перед фиксацией требуется рабочая установка apatite (pip install apatite).

Создание хорошей записи

На момент написания статьи для создания действительной записи необходимо следующее:

Название проекта

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

Описание проекта

Поскольку это список Awesome Python Application, и все записи должны быть бесплатными/с открытым исходным кодом, нет необходимости включать термины «Python», «Application», «free» или «open-source» в описание проекта.

Вместо этого сосредоточьтесь на архитектуре (например, веб-приложение против CLI), дизайне, функциях и целевой аудитории.

Ссылки

В конечном счёте APA — это ссылки и рекомендации, поэтому мы хотим как можно больше ссылок. Некоторые распространённые формы:

• repo_url — обязательная ссылка на репозиторий кода. Если неясно, как клонировать/скачать код, также следует указать clone_url, если репозиторий git, hg или bzr.
• home_url — целевая страница проекта, если она отличается от URL репозитория.
• docs_url — документация, руководство пользователя или руководство по интеграции.
• fund_url — ссылка на монетарную поддержку/спонсирование проекта.
• demo_url — для проектов, которые можно самостоятельно разместить, сайт, демонстрирующий проект в действии, если он отличается от home_url.
• wp_url — ссылка на статью Википедии о проекте (может быть раздел).
• gh_url — ссылка на зеркало GitHub, если у не-GitHub-проекта оно есть.
• pypi_url — ссылка на страницу проекта PyPI, когда у проекта она есть. (большинство приложений не имеют; PyPI в основном предназначен для библиотек).

Другие ключи вида *_url также будут обрабатываться автоматически. Редко есть причина включать один и тот же URL под несколькими ключами, поэтому просто выберите ближайший.

Теги

Выберите любые подходящие элементы из tagsonomy в верхней части projects.yaml. На данный момент нам требуется хотя бы один тег «тема» с возможностью вторичного тега и целевой платформы.

Обратите внимание, что для целевой платформы «linux» обычно означает настольные/однопользовательские программы, тогда как «server» используется для многопользовательских приложений.

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

Советы

1. Список projects.yaml автоматически сортируется и нормализуется. Не беспокойтесь о том, чтобы найти подходящее место для добавления проекта. Добавьте его сверху или снизу со значениями в любом порядке, и процесс рендеринга apatite позаботится обо всём остальном.
2. При добавлении проекта с сопровождающими на GitHub попробуйте использовать сообщение фиксации «добавление проекта-xyz /cc @maintainer1 @maintainer2», чтобы сопровождающие были в курсе их присутствия в списке. Это также помогает в случае, если мы сделаем... Критерии отбора проектов

Возможно, в тексте есть ошибки или неточности.

Проект может быть включён в список при соблюдении следующих условий:

• Это свободное программное обеспечение с онлайн-репозиторием.
• Значительная часть функциональности реализована на Python.
• Проект широко известен или активно используется в определённой нише.
• Он поддерживается и продолжает функционировать на соответствующих платформах.
• Это приложение, а не библиотека или фреймворк.

Существуют дополнительные критерии, которые помогают формировать список:

1. Обычно достаточно одного коммита за последний год. На момент написания более 95 % из 360 проектов имели коммит за последний год (отметим, что это соотношение постоянно меняется).
2. Проекты с менее чем 100 коммитами и тремя участниками часто слишком молодые и должны быть пересмотрены.
3. Категории, архитектуры или области, которые недостаточно представлены в списке, заслуживают особого внимания (хотелось бы видеть больше проектов на Beeware, мобильных, браузерных и игровых проектов).
4. Чтобы расширить аудиторию, проекты должны быть безопасными для работы.
5. Технологии и хайп сами по себе не делают приложение отличным. Для духа списка гораздо важнее ценность, которую проект предоставляет пользователям.
6. Хорошие кандидаты обычно не существуют только для того, чтобы продемонстрировать базовую технологию.

Что такое приложение?

Хотя обычно легко отличить библиотеку от приложения, бывают сложные случаи. Вот несколько вопросов, которые помогут классифицировать программное обеспечение на Python:

• Предпочитает ли программное обеспечение конфигурацию без кода (переменные среды, файлы ini/yaml/toml/json, аргументы CLI и т. д.) вместо написания большого количества кода на Python? Сначала программное обеспечение может показаться приложением, но если оно требует написания слишком большого объёма кода, это может быть фреймворк.
• Есть ли у программного обеспечения система плагинов? Продолжая предыдущую мысль, приложения не требуют написания кода, но хорошо разработанные могут иметь структурированный способ расширения.
• Устанавливается ли программное обеспечение через менеджер пакетов pip? Установка с помощью системных менеджеров пакетов и установщиков обычно является хорошим признаком того, что вы смотрите на приложение.

Общие цели

APA — не единственный список программного обеспечения на Python (https://github.com/mahmoud/awesome-python-applications/blob/master/TODO.md#other-lists). Ниже представлены цели этого списка по сравнению со многими другими:

1. Более чёткие критерии включения.
2. Гарантированный качественный обзор (экспертная оценка и т. п.).
3. Только приложения, никаких фреймворков или библиотек.
4. Ссылки, особенно ссылки на репозитории, для автоматического контроля качества (мёртвые ссылки, мёртвые проекты).
5. Документы, удобные для чтения человеком, и структурированные данные, удобные для машинной обработки.
6. Открытый исходный код: можно внести свой вклад через PR.
7. Наличие тегов с несколькими измерениями (таксономия).
8. Долгосрочное видение.

Если у вас есть идеи о том, как достичь вышеуказанного, мы будем рады их услышать. Пожалуйста, создайте задачу (https://github.com/mahmoud/awesome-python-applications/issues).