Различия между версиями 3 и 16 (по 13 версиям)

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

Содержание

Вклад в BlueBream
Ресурсы для разработчиков
Процесс разработки
Технические решения
Руководство по написанию документации
1. Обзор
2. Подсказки

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

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

Подсказки

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

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

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

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

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

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

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

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

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

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

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

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

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

-  ⇤ ← Версия 3 от 2010-07-05 14:57:58 → 
  Размер: 1021
  Редактор: RostislavDzinko
  Комментарий:
+   ← Версия 16 от 2010-07-06 12:36:22 → ⇥
  Размер: 10487
  Редактор: 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 следующим образом (анонимный доступ):
 Строка 13:
-svn co svn://svn.zope.org/repos/main/bluebream/trunk bluebream
You can also become a committer after signing a contributor agreement.
+ {{{#!highlight bash
   svn co svn://svn.zope.org/repos/main/bluebream/trunk bluebream
 }}}
-Строка 16:
+Строка 17:
- * Project blog
+ Вы можете делать изменения в репозиторий после подписания [[http://docs.zope.org/developer/becoming-a-committer.html|соглашения вкладчика]].
-Строка 18:
+Строка 19:
- * The bugs and issues are tracked at launchpad.
+ * [[http://bluebream.posterous.com/|Блог проекта]]
-Строка 20:
+Строка 21:
- * BlueBream Wiki.
+ * Баги отслеживаются на [[https://launchpad.net/bluebream|launchpad]]
-Строка 22:
+Строка 23:
- * PyPI page
+ * [[http://wiki.zope.org/bluebream|BlueBream Wiki]]
-Строка 24:
+Строка 25:
- * Documentation
+ * [[http://pypi.python.org/pypi/bluebream|Страница PyPI]]
-Строка 26:
+Строка 27:
- * Twitter
+ * [[http://bluebream.zope.org/|Documentation]]
-Строка 28:
+Строка 29:
- * Mailing list
+ * [[http://twitter.com/bluebream|Twitter]]
-Строка 30:
+Строка 31:
- * IRC Channel: #bluebream at irc.freenode.net
+ * [[https://mail.zope.org/mailman/listinfo/bluebream|Список рассылки]]
-Строка 32:
+Строка 33:
- * Buildbot
+ * IRC канал: [[http://webchat.freenode.net/?randomnick=1&channels=bluebream|#bluebream]] на irc.freenode.net

 * [[http://zope3.afpy.org/buildbot|Buildbot]]
-Строка 38:
+Строка 41:
+Процедура создания релизов, которой следует !BlueBream очень похожа на ту, которой следует ZTK.

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

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

 * Все тесты пройдены
 * Все локальные изменения поступили в репозиторий
 * Журнал изменений (changelog) обновлен.
-Строка 40:
+Строка 53:
+ * Сделать объявление в списке рассылки
 * Сделать запись в блоге
 * Обновить статус в twitter
-Строка 41:
+Строка 58:
+Список проверки релиза на данный момент управляется через вики: http://wiki.zope.org/bluebream/ReleaseChecklist

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

 * !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.

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

== Обзор ==

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

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

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

Целью этих подсказок не является покрытие всех вариантов использования английского языка и ошибок построения текстов. Я считаю, что лучшим ресурсов по правилам построения текстов является [[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]]

== Подсказки ==

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

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

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

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

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

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

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

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

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

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

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

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

Страница

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