|
| 1 | +Приветствуются все виды изменений. Не стесняйтесь предлагать броские и смешные названия для существующих примеров. Цель - сделать эту коллекцию как можно более интересной для чтения. Вот несколько способов, с помощью которых вы можете внести свой вклад, |
| 2 | + |
| 3 | +- Если вы заинтересованы в переводе проекта на другой язык (некоторые люди уже делали это в прошлом), пожалуйста, не стесняйтесь открыть тему и дайте мне знать, если вам нужна какая-либо помощь. |
| 4 | +- Если изменения, которые вы предлагаете, значительны, то создание issue перед внесением изменений будет оценено по достоинству. Если вы хотите поработать над issue (это очень рекомендуется), выразите свою заинтересованность и вы будете назначены исполнителем. |
| 5 | +- Если вы добавляете новый пример, настоятельно рекомендуется создать issue, чтобы обсудить ее перед отправкой изменений. Для добавления нового примера вы можете использовать следующий шаблон: |
| 6 | + |
| 7 | +<pre> |
| 8 | +### ▶ Какое-то причудливое название. * |
| 9 | +* в конце названия означает, что пример был добавлен недавно. |
| 10 | + |
| 11 | +```py |
| 12 | +# Подготовка кода. |
| 13 | +# Подготовка к волшебству... |
| 14 | +``` |
| 15 | + |
| 16 | +**Вывод (версия Python):** |
| 17 | +```py |
| 18 | +>>> triggering_statement |
| 19 | +Вероятно, неожиданный вывод |
| 20 | + |
| 21 | +``` |
| 22 | +(Необязательно): Одна строка, описывающая неожиданный вывод. |
| 23 | + |
| 24 | +#### 💡 Объяснение: |
| 25 | +* Краткое объяснение того, что происходит и почему это происходит. |
| 26 | + ```py |
| 27 | + Подготовка примеров для пояснения (при необходимости) |
| 28 | + ``` |
| 29 | + |
| 30 | + **Вывод:** |
| 31 | + ```py |
| 32 | + >>> trigger # пример, облегчающий понимание магии |
| 33 | + # обоснованный вывод |
| 34 | + ``` |
| 35 | +</pre> |
| 36 | + |
| 37 | +Несколько моментов, которые стоит учитывать при написании примера, |
| 38 | + |
| 39 | +- Если вы решили отправить новый пример без создания issue и обсуждения, пожалуйста, проверьте проект, чтобы убедиться, что в нем уже нет похожих примеров. |
| 40 | +- Старайтесь быть последовательными в именах и значениях, которые вы используете для переменных. Например, большинство имен переменных в проекте имеют вид `some_string`, `some_list`, `some_dict` и т.д. Вы увидите много `x` для однобуквенных имен переменных, и `"wtf"` в качестве значений для строк. В проекте нет строгой схемы, как таковой, но вы можете взглянуть на другие примеры, чтобы понять суть. |
| 41 | +- Старайтесь быть как можно более креативными, чтобы добавить элемент "сюрприза" во время подготовки примеров. Иногда это может означать написание фрагмента, который здравомыслящий программист никогда бы не написал. |
| 42 | +- Также не стесняйтесь добавлять свое имя в список [контрибьюторов](/CONTRIBUTORS.md). |
| 43 | + |
| 44 | +**Некоторые часто задаваемые вопросы** |
| 45 | + |
| 46 | + Что это такое после каждого заголовка сниппета (###) в README: <!-- ID примера: 30f1d3fc-e267-4b30-84ef-4d9e7091ac1a --->? Нужно ли его добавлять вручную или можно игнорировать при создании новых сниппетов? |
| 47 | + |
| 48 | +Это случайный UUID, он используется для идентификации примеров в нескольких переводах проекта. Как контрибьютор, вы не должны беспокоиться о том, как он используется, вы просто должны добавлять новый случайный UUID к новым примерам в этом формате. |
| 49 | + |
| 50 | + Куда следует добавлять новые сниппеты? В начало/в конец раздела? |
| 51 | + |
| 52 | +При определении порядка учитывается множество факторов (зависимость от других примеров, уровень сложности, категория и т.д.). Я бы предложил просто добавить новый пример в конец раздела, который вы считаете более подходящим (или просто добавить его в раздел "Разное"). О его порядке можно будет позаботиться в будущих редакциях. |
| 53 | + |
| 54 | + В чем разница между разделами (первые два очень похожи)? |
| 55 | + |
| 56 | +Раздел "Напрягите мозг" содержит более надуманные примеры, с которыми вы не столкнетесь в реальной жизни, в то время как раздел "Скользкие склоны" содержит примеры, с которыми можно чаще сталкиваться при программировании. |
| 57 | + |
| 58 | + Перед оглавлением написано, что для его создания использовался markdown-toc -i README.md --maxdepth 3. Пакет pip markdown-toc не содержит ни флагов -i, ни --maxdepth. Какой пакет имеется в виду, или какая версия этого пакета? |
| 59 | + Должна ли новая запись в оглавлении для фрагмента быть создана с помощью вышеуказанной команды или вручную (в случае, если вышеуказанная команда делает больше, чем просто добавляет запись)? |
| 60 | + |
| 61 | +Мы используем пакет [markdown-toc](https://www.npmjs.com/package/markdown-toc) npm для создания ToC (содержание). Однако у него есть некоторые проблемы со специальными символами (не уверен, что они уже исправлены). Чаще всего я просто вставляю ссылку toc вручную в нужное место. Инструмент удобен, когда мне нужно сделать большую перестановку, в остальных случаях просто обновлять toc вручную удобнее. |
| 62 | + |
| 63 | +Если у вас есть вопросы, не стесняйтесь спрашивать в [issue](https://github.com/satwikkansal/wtfpython/issues/269) (спасибо [@LiquidFun](https://github.com/LiquidFun) за ее создание). |
0 commit comments