Дополнен раздел «Разработка»

docs/source/development/development_process.rst

@@ -0,0 +1,47 @@
+Процесс разработки
+==================
+
+Общий подход
+------------
+
+Разработка игры идёт в духе «инкреметального прототипирования», что предполагает прохождение каждой «фичи» через последовательность прототипов, совершенствующих её реализацию. Не делается попыток с первого раза написать самый правильный и самый крутой код. Как следствие:
+
+- новая «фича» реализуется самым простым и понятным образом, без переусложнений и оптимизаций;
+- по мере развития игры (и анализа её работы), логика «фичи» уточняется и совершенствуется;
+- если «фича» оказывается достаточно независимой, она выделяется в отдельную библиотеку.
+
+Следствием такого подхода является постоянный рефакторинг проекта.
+
+В случае крупных инфраструктурных изменений их допустимо не применять сразу ко всему проекту, а только к тем частям, над которыми идёт работа в настоящий момент. Старый код вычищается тогда, когда появляется необходимость изменения компонента, в котором он находится.
+
+Тесты
+-----
+
+Весь важный код покрывается тестами.
+
+Весь не важный код покрывается тестами по возможности.
+
+Работа с версиями
+-----------------
+
+Разработу ведём по git-flow:
+
+- http://nvie.com/posts/a-successful-git-branching-model/
+- https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
+
+Master ветка всегда содержит в себе текущую рабочую версию проекта (ту, которая сейчас запущена на сайте).
+
+Работа над новой версией ведётся в ветке develop. По завершении работы, делается тег и изменения подливаются в master.
+
+**Всю работу надо делать в ветке develop или её ветке. Изменения применять к ней же.**
+
+Требования к изменениям
+-----------------------
+
+Предлагаемые вами изменения в обязательном порядке должны:
+
+- быть в виде одного патча (pull request должен содержать 1 коммит);
+- быть покрыты тестами;
+- не использовать устаревшую функциональность;
+
+Желательно, чтобы они сопровождались документацией.

docs/source/development/directions_of_development.rst

@@ -0,0 +1,57 @@
+Направления разработки
+======================
+
+Планов по развитию «Сказки» у нас больше, чем свободных рук, поэтому всегда есть крупные задачи, ожидающие своей реализации.
+
+Эта страница посвящена как раз таким задачам и будет интересна опытным разработчикам с большим количеством свободного времени.
+
+Если вы хотите активно участвовать в разработке игры — эти задачи для вас. Подробно про каждую из них может рассказать Tiendil.
+
+**Наиболее важной задаче сейчас является рефакторинг проекта с монолитного на набор микросервисов.**
+
+
+Рефакторинг
+-----------
+
+Как сказано в :doc:`описании процесса разработки <development_process>`, игра находится в состоянии непрерывного рефакторинга. У нас всегда найдётся место, в котором нужно навести порядок :-)
+
+- Оптимизация тестов — в проекте более 4000 автоматических тестов, работу которых можно ускорить и упростить.
+- Эксперименты с организацией кода привели к неудобной системе обёрток над Django view, которую надо заменить на более удобную.
+- Те же эксперименты переусложнили работу с объектами игры.
+- Бразуерный интерфейс игры реализован на старых технологиях, необходимо его актуализировать (или переписать полностью).
+
+Отдельно хочется отметить идущий рефакторинг проекта с монолитного на набор микросервисов. У этой активности две цели:
+
+- уменьшение связанности логики игры (чтобы упростить внесение изменений);
+- получение независимых от логики игры переиспользуемых сервисов.
+
+Большую часть подсистем игры предполагается выделять в отдельные сервисы, поэтому сейчас можно выбрать для работы наиболее интересный (и нужный для ваших проектов) кусок функциональности.
+
+
+Существующая функциональность
+-----------------------------
+
+Часть фунциональности игры реализована в минимально необходимом виде, поэтому её можно (и нужно) развивать.
+
+- Форум (нужны система модерации, доработка статистики, исправление ошибок, приведение кода в порядок).
+- Гильдии (нужны звания, взаимодействие с форумом, продвинутые настройки, статистика, развитие геймплея).
+- Игровая статистика (увеличение собираемых параметров, их анализ).
+- Лингвистика (упрощение интерфейса и логики работы).
+- На сайте игры необходимо внедрить `семантическую разметку <http://schema.org/>`_.
+- Необходимо развивать функциональность генерации и отображения карты (нужны библиотеки GUI для разных платформ, улучшение интерфейса и расширение функциональности).
+
+
+Новая функциональность
+----------------------
+
+- Галерея изображений и развитие фольклора — игра также должна стать площадкой для творчества игроков. Необходимо обеспечить наших автором всеми удобствами.
+- Веб API 2.0 — качество организованное.
+- Сервис генерации информеров для форумов (сейчас используется внешняя реализация одного из игроков).
+- Прототипирование оригинальных фич веб-интерфейса.
+- Сервис выдачи краткой информации по объектам игры + его интеграция в веб-интерфейс.
+
+
+Проекты-спутники
+----------------
+
+Вы можете присоединиться к одному из :doc:`проектов игроков <../3rd_party>` или начать свой.

docs/source/development/guides/index.rst

@@ -0,0 +1,7 @@
+Руководства
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   mails

docs/source/development/guides/mails.rst

@@ -0,0 +1,53 @@
+Конфигурация работы с почтой
+============================
+
+На этой странице будет представлено подробное руководство по настройке работы игры с почтой. Данный момент не существенен для разработки, но критичен для публикации игры, поскольку многие активности (регистрация, изменение пароля, нотификации) требуют отправки почты.
+
+Конфигурацию работы игры с почтой можно разделить на 2 части: настройка отправки писем и настройка соединения с почтовым сервером.
+
+Поскольку вопрос почтовых рассылок сложный, мы приветствуем всяческие дополнения в это руководство.
+
+Отправка писем
+--------------
+
+За отправку писем отвечает отдельный фоновый рабочий ``post_service``. Часть его настроек можно найти в ``the_tale.post_service.conf`` и переопределить в ``settings_local.py`` дописав к их именам ``POST_SERVICE_``. Эти настройки снабжены соответствующими комментариями, которые повторяться тут не будут.
+
+Для включения отправки писем необходимо установить
+
+``POST_SERVICE_ENABLE_MESSAGE_SENDER = True``
+
+И установить значение ``allowed`` в таблице ``settings`` (через админку Django) по ключу равному значению ``SETTINGS_ALLOWED_KEY``.
+
+Кроме того, в ``settings_local.py`` необходимо установить следующие параметры
+
+- ``SERVER_EMAIL`` — почтовый адрес от которого по умолчанию будут отправляться письма.
+- ``EMAIL_NOREPLY`` — почта, которая будет писаться в письмах, на которые игроки не должны отвечать, тут можно указать длинное значение вроде ``u'«Сказка» <no-reply@the-tale.org>'``
+- ``EMAIL_SUPPORT`` — почта службы поддержки, тут можно указать длинное значение вроде ``u'«Сказка» <support@the-tale.org>'``
+- ``EMAIL_SUPPORT_SHORT`` — короткий адрес службы поддержки (только сама почта, без вставки имени и прочего)
+
+Настройка соединения с почтовым сервером
+----------------------------------------
+
+Отправлять почту мы можем как через собственный почтовый сервис (например, настроив `Postfix <http://www.postfix.org/>`_) либо через один из существующих (например, через `GMail <http://gmail.com/>`_).
+
+В каждом случае есть свои нюансы, касающиеся массовых рассылок и попадания под спам фильтры. Но в начале проще использовать существующий сервис (при запуске, Сказка использовала GMail, потом перешла на Postfix).
+
+Соединение с почтовым сервисом настраивается `стандартным для Django способом <https://docs.djangoproject.com/en/1.8/topics/email/>`_.
+
+Для собственного сервиса будет достаточно указать следующие настройки
+
+- ``EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'``
+- ``EMAIL_HOST_USER`` — пользователь сервиса с правами отправки почты
+- ``EMAIL_HOST_PASSWORD`` — пароль пользователя
+
+Для использования сторонних сервисов, возможно, надо будет добавить несколько других параметров (см. в конфигурации Django и этот пост)
+
+Отправка писем во время разработки
+----------------------------------
+
+Для разработки игры обычно нет необходимости настраивать отправку почты, поскольку для большинства случаев она не нужна.
+
+Поэтому отправку почты можно настроить в каталог на файловой системе, например, так:
+
+- ``EMAIL_BACKEND = 'django.core.mail.backends.filebased.EmailBackend'``
+- ``EMAIL_FILE_PATH = '/tmp/emails'``

docs/source/development/how_to_start.rst

@@ -0,0 +1,23 @@
+Как присоединиться?
+===================
+
+**Спасибо что интересуетесь нашим проектом!** Мы (в особенности Tiendil) обещаем всеми силами помогать вам.
+
+Присоединиться в разработке можно разными способами, все они привычны для open souce проектов:
+
+- Помогите улучшить нашу докумнетацию — её не бывает много.
+- Напишите новый юнит-тест — это поможет познакомиться с интересующей вас частью игры и сделает её немного надёжнее.
+- Подумайте над небольшим улучшением интерфейса — мы не можем уделять ему достаточно внимания, поэтому там всегда есть место для улучшения.
+- Выберите одну из `задач для новичков <https://github.com/the-tale/the-tale/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_.
+- Из игры постепенно выделяются :doc:`дочерние проекты <child_projects>`, которые могут пригодиться другим разработчикам. Вы можете помочь в их разработке.
+- Если вы опытный разработчик, можете взяться за одну из :doc:`больших задач <directions_of_development>`.
+
+Среди меток каждой `задачи <https://github.com/the-tale/the-tale/issues>`_ вы обязательно найдёте указание на её сложность, тип и компонент игры, к которому она относится.
+
+Кроме этого вы можете помочь игре как `политик, автор лингвистики или фольклора <http://the-tale.org/guide/how-to-help>`_.
+
+Прежде чем браться за какую-либо задачу:
+
+- Научитесь запускать :doc:`локальную версию игры <install>`.
+- Напишите Tiendil-у (сделать это можно на сайте игры или по любому из контактов на `tiendil.org <http//tiendil.org/about/>`_). Он подробно расскажет про все нюансы выбранной задачи.
+- Прочтите :doc:`про организацию процесса разработки <development_process>`.

docs/source/development/index.rst

@@ -1,9 +1,16 @@
 Разработка
 ==========
 
+Все обсуждения, связанные с разработкой, можно вести на `форуме игры <http://the-tale.org/forum/subcategories/28>`_.
+
+Важные новости для разработчиков публикуются в `отдельной теме на форуме игры <http://the-tale.org/forum/threads/4017>`_.
+
 .. toctree::
    :maxdepth: 2
-   :caption: Содержание
 
    install
+   how_to_start
+   development_process
    child_projects
+   directions_of_development
+   guides/index

docs/source/external_api/index.rst

@@ -7,7 +7,6 @@
 
 .. toctree::
    :maxdepth: 2
-   :caption: Содержание
 
    intro
    methods

docs/source/game_designe/characters/index.rst

@@ -5,7 +5,6 @@
 
 .. toctree::
    :maxdepth: 2
-   :caption: Персонажи
    :glob:
 
    character*

docs/source/game_designe/index.rst

@@ -7,7 +7,6 @@
 
 .. toctree::
    :maxdepth: 2
-   :caption: Содержание
 
    races
    characters/index