Вклад в 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, они направлены в первую очередь на написание документации к программному обеспечению, или всему, что является ему технически эквивалентным.

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

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

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

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

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

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

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

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

Документации/Bluebream/BluebreamДляРазработчиков (последним исправлял пользователь RostislavDzinko 2010-07-06 14:47:47)

-  ⇤ ← Версия 10 от 2010-07-05 15:04:25 → 
  Размер: 1924
  Редактор: RostislavDzinko
  Комментарий:
+   ← Версия 15 от 2010-07-06 12:23:40 → ⇥
  Размер: 9052
  Редактор: RostislavDzinko
  Комментарий:
-Удаления помечены так.
+Добавления помечены так.
 Строка 11:
- * The source code is managed at Zope reposistory. You can checkout the trunk code like this (Anonymous access):
+ * Исходный код управляется через [[http://svn.zope.org/bluebream|репозиторий Zope]]. Вы можете вытянуть исходники из trunk следующим образом (анонимный доступ):
 Строка 19:
- * Project blog
+ * [[http://bluebream.posterous.com/|Блог проекта]]
 Строка 21:
- * The bugs and issues are tracked at launchpad.
+ * Баги отслеживаются на [[https://launchpad.net/bluebream|launchpad]]
 Строка 23:
- * !BlueBream Wiki.
+ * [[http://wiki.zope.org/bluebream|BlueBream Wiki]]
 Строка 25:
- * PyPI page
+ * [[http://pypi.python.org/pypi/bluebream|Страница PyPI]]
 Строка 27:
- * Documentation
+ * [[http://bluebream.zope.org/|Documentation]]
 Строка 29:
- * Twitter
+ * [[http://twitter.com/bluebream|Twitter]]
 Строка 31:
- * Mailing list
+ * [[https://mail.zope.org/mailman/listinfo/bluebream|Список рассылки]]
 Строка 33:
- * IRC Channel: #bluebream at irc.freenode.net
+ * IRC канал: [[http://webchat.freenode.net/?randomnick=1&channels=bluebream|#bluebream]] на irc.freenode.net
 Строка 35:
- * Buildbot
+ * [[http://zope3.afpy.org/buildbot|Buildbot]]
 Строка 41:
+Процедура создания релизов, которой следует !BlueBream очень похожа на ту, которой следует ZTK.

Часть [[http://docs.zope.org/zopetoolkit/process/releasing-software.html|официального руководства по созданию релизов]] находится в файле ''CHANGES.txt''. Это важный шаг, который не может быть автоматизирован.

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

 * Все тесты пройдены
 * Все локальные изменения поступили в репозиторий
 * Журнал изменений (changelog) обновлен.
-Строка 42:
+Строка 52:
+ * Сделать объявление в списке рассылки
 * Сделать запись в блоге
 * Обновить статус в twitter
-Строка 45:
+Строка 59:
+Список проверки релиза на данный момент управляется через вики: http://wiki.zope.org/bluebream/ReleaseChecklist
-Строка 46:
+Строка 62:
+ * !BlueBream - это “веб фреймворк”.

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

 * Есть только один публично доступный API известный как '''bluebream - пакет'''. Этот API - точка входа, предоставляемая setuptools, который использует !PasteScript:
 {{{#!highlight python
  entry_points={
  "paste.paster_create_template":
    ["bluebream = bluebream.bluebream_base.template:BlueBream",
     ]}
 }}}

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

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

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

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

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

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

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

 * дополнительные пакеты, которые содержатся в пространствах имен, таких как '''zc''', '''z3c''', или других, будут добавлены в будущем, но не есть частью релиза версии 1.0.
-Строка 52:
+Строка 96:
+Писать доступно очень тяжело. Объяснение сложного предмета, такого как программное обеспечение, новичку - очень сложная задача, потому что Вы, писатель, уже владеете этим предметом перед началом написания.

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

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

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

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

 * [[http://www.dsiegel.com/tips/wonk9/usage.html|English usage in Cyberspace]]
 * [[http://alabanza.com/kabacoff/Inter-Links/|Writer’s General Reference]]

Страница

Пользователь