Для разработчиков

Вклад в BlueBream

Если вы заинтересованы во внесении вклада в проект BlueBream, посетите вики страницу: http://wiki.zope.org/bluebream/ContributingToBlueBream

Ресурсы для разработчиков

• Исходный код управляется через репозиторий Zope. Вы можете вытянуть исходники из trunk следующим образом (анонимный доступ):

     1    svn co svn://svn.zope.org/repos/main/bluebream/trunk bluebream
  

  Вы можете делать изменения в репозиторий после подписания соглашения вкладчика.

• Блог проекта

• Баги отслеживаются на launchpad

• BlueBream Wiki

• Страница PyPI

• Documentation

• Twitter

• Список рассылки

• IRC канал: #bluebream на irc.freenode.net

• Buildbot

Процесс разработки

Создание релизов

Процедура создания релизов, которой следует BlueBream очень похожа на ту, которой следует ZTK.

Часть официального руководства по созданию релизов находится в файле CHANGES.txt. Это важный шаг, который не может быть автоматизирован.

Другими словами, перед началом релиза убедитесь в том, что:

• Все тесты пройдены
• Все локальные изменения поступили в репозиторий
• Журнал изменений (changelog) обновлен.

Пострелизные шаги

• Сделать объявление в списке рассылки
• Сделать запись в блоге
• Обновить статус в twitter

Список проверки релиза

Список проверки релиза на данный момент управляется через вики: http://wiki.zope.org/bluebream/ReleaseChecklist

Технические решения

• BlueBream - это “веб фреймворк”.

• Допускается сокращение BlueBream как Bream или BB. На данный момент сокращение BB становится все более популярным в сообществе.

• Есть только один публично доступный API известный как bluebream - пакет. Этот API - точка входа, предоставляемая setuptools, который использует PasteScript:

     1   entry_points={
     2   "paste.paster_create_template":
     3     ["bluebream = bluebream.bluebream_base.template:BlueBream",
     4      ]}
  

• Весь код фреймворка использует пространства имен для пакетов: zope или zope.app, хотя в будущем может использоваться и bb.

• проект bluebream состоит из шаблонов проектов.

• веб сайт bluebream - место хранения веб содержимого.

• bbkit - место хранения инфраструктуры KGS.

• BlueBream 1.0 должен обеспечивать переход с Zope 3.4 KGS.

• Любая команда оболочки (shell command), которая должна повторятся после создания проекта не автоматизируется через шаблон проекта.

• Запуск bootstrap.py и buildout в проекте не должны выполнятся во время создания шаблона проекта исходя из предыдущего пункта. Другая причина в том, что так проще работать с системами контроля версий.

• дополнительные пакеты, которые содержатся в пространствах имен, таких как zc, z3c, или других, будут добавлены в будущем, но не есть частью релиза версии 1.0.

Руководство по написанию документации

Обзор

Писать доступно очень тяжело. Объяснение сложного предмета, такого как программное обеспечение, новичку - очень сложная задача, потому что Вы, писатель, уже владеете этим предметом перед началом написания.

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

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

Целью этих подсказок не является покрытие всех вариантов использования английского языка и ошибок построения текстов. Я считаю, что лучшим ресурсов по правилам построения текстов является The Elements of Style, автор William Strunk, Jr. Также доступно продолжение этой книги, отредактированное и дополненное автором E. B. White (и наиболее часто встречающееся в книжных магазинах). The Elements of Style - незаменимая книга для всех, чья задача - писать чистым английским языком. Хотя правила, которые здесь описываются, созданы под впечатлением, и часто совпадают, с правилами и концепциями, описанными в The Elements of Style, они направлены в первую очередь на написание документации к программному обеспечению, или всему, что является ему технически эквивалентным.

Вот несколько интересных ссылок на другие похожие ресурсы:

• English usage in Cyberspace

• Writer’s General Reference

Подсказки

Говорите прямо с читателем

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

Используйте первое лицо как можно реже, и только тогда, когда указываете на себя: писателя. Мы не должно быть использовано, когда вы имеете в виду себя вместе с читателем, а относится только к нескольким авторам (если их несколько). Вот пример текста, объединяющего читателя вместе с автором в одном контексте:

• Когда мы добавляем новый метод в этот класс, он переопределит все методы с таким же именем, которые определены в наших подклассах.

Такое построение часто называют Королевское "Мы" (The Royal We). Поправить это можно простых изменением:

• Когда вы добавляете новый метод в этот класс, он переопределит все методы с таким же именем, которые определены в ваших подклассах.

Будьте напористым

Никогда не говорите в слабой, неопределенной, возможностной манере.

Как описано в The Elements of Style (правило #11), используйте активное состояние. Это настолько распространенная ошибка, что она стоит того, чтобы повторить ее здесь с несколькими примерами. Активное состояние значит взаимодействие с объектом, поданное с помощью глагола в активном состоянии. И наоборот, пассивное состояние, обычно, включаете описание состояния объекта, который постоянно делает какое-нибудь бесконечное действие. Например:

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

Вот те же предложения в активном состоянии. Заметьте, как приходится перестраивать предложения:

• Запомните, ZPublisher отказывается публиковать метод, который не имеет строки документации.
• Экраны, оформленные в виде закладок, обеспечивают стандартное соглашение для управления продуктом.

Никогда не говорите возможностными понятиями, как может быть, возможно, или наверное. Это зачастую является бессознательным действием при написании документации до того, как создано само программное обеспечение. Будьте напористым, и показывайте, как есть, а не как может быть. От возможно откажитесь вообще. Может быть и наверное могут быть заменены на есть. Должен также иногда подпадает под это правило.

Объясняйте ключевые идеи простыми понятиями

Предоставляйте простые примеры

Избегайте разговорных выражений

Предоставляйте ответы, не порождайте вопросы

Пересмотрите предложения, которые говорят мало, или ничего