Персональные инструменты
 

ShowTeamWork — различия между версиями

Материал из CustisWiki

Перейти к: навигация, поиск
м (1 версия)
м (stw-config.py)
Строка 141: Строка 141:
 
Бесплатно и патриотично!
 
Бесплатно и патриотично!
 
Если хотите публиковать свои ролики, напоминаем о пока еще существующих цифровых правах на музыку и рекомендуем использовать только свободно доступную музыку — [http://www.jamendo.com/en/tag/ambient тут огромный выбор музыки в стиле Ambient].
 
Если хотите публиковать свои ролики, напоминаем о пока еще существующих цифровых правах на музыку и рекомендуем использовать только свободно доступную музыку — [http://www.jamendo.com/en/tag/ambient тут огромный выбор музыки в стиле Ambient].
 +
 +
=== Инсталляция ===
 +
 +
Проект (исходники и бинарники) хостится на Google Code — http://code.google.com/p/showteamwork/.
 +
 +
То есть скомпилированные под Windows бинарники, вместе можно скачать [http://code.google.com/p/showteamwork/downloads/list отсюда],
 +
а если хотите поучаствовать в разработке — см. http://code.google.com/p/showteamwork/source/checkout
 +
 +
Единственное софтверное требование под Windows — наличие <tt>Java</tt> (все остальное идет в комплекте).
 +
 +
Под Linux нужно установить (из исходников или пакетами — неважно):
 +
* <tt>ffmpeg</tt>
 +
* <tt>mencoder</tt> (из проекта <tt>mplayer</tt>)
 +
* <tt>python</tt> (для надежности версии 2.5 или 2.6).
 +
* <tt>gource</tt> http://code.google.com/p/gource/
 +
и сделать, чтобы эти утилиты были прописаны в путях.
 +
 +
Cразу посмотрите каталог <tt>samples</tt>, должно быть все понятно.
 +
 +
Чуть позже, мы подробно распишем здесь назначение каждой настройки.
 +
  
 
=== Быстрый старт ===
 
=== Быстрый старт ===
Строка 149: Строка 170:
  
  
Зайдите в каталог проекта, т.е. воркспейс под одной из систем контроля версий ( <tt>CVS</tt>, <tt>SVN</tt>, <tt>GIT</tt>, <tt>Bazaar</tt>, <tt>Mercurial</tt>), причем не обязательно верхний уровень — можно на два-три уровня ниже, и вызовите  
+
Зайдите в каталог проекта, то есть воркспейс под одной из систем контроля версий (<tt>CVS</tt>, <tt>SVN</tt>, <tt>GIT</tt>, <tt>Bazaar</tt>, <tt>Mercurial</tt>), причем не обязательно верхний уровень — можно на два-три уровня ниже, и вызовите
 
<tt>showteamwork.exe</tt>, и отправляйтесь пить кофе.
 
<tt>showteamwork.exe</tt>, и отправляйтесь пить кофе.
  
Строка 161: Строка 182:
  
 
=== Схема генерации ===
 
=== Схема генерации ===
 +
 +
Кликабельная (!) схема генерации:
  
 
<graph>
 
<graph>
Строка 192: Строка 215:
  
 
   node    [fillcolor="#0084FF" shape=egg]
 
   node    [fillcolor="#0084FF" shape=egg]
   scenario [label="История \n stw-scenario.txt"]
+
   scenario [label="История \n stw-scenario.txt" URL="#stw-scenario.txt"]
   audio    [label="Музыка \n stw-audio.mp3"]
+
   audio    [label="Музыка \n stw-audio.mp3" URL="#stw-audio.mp3"]
   config  [label="Настройки \n stw-config.py"]
+
   config  [label="Настройки \n stw-config.py" URL="#stw-config.py"]
   filters  [label="Фильтры \n stw-filter.py"]
+
   filters  [label="Фильтры \n stw-filter-events.py " URL="#stw-filter-events.py"]
  
   activity [label="Обработанная \n активность\n activity.xml"]
+
   activity [label="Обработанная \n активность\n activity.xml" URL="#activity.xml"]
  
 
   filters -> activity
 
   filters -> activity
 
   vcslog  -> activity
 
   vcslog  -> activity
  
   cache    [label="Кеш-данные"]
+
   cache    [label="Кеш-данные" URL="#TemporaryCache"]
  
  
Строка 236: Строка 259:
  
 
=== getlog.py ===  
 
=== getlog.py ===  
При отсутствии известного системе логфайла, <tt>ShowTeamWork</tt> пытается вызвать скрипт <tt>getlog.py</tt>, где вы пропишете, что и откуда надо тянуть. Например, вы собираетесь визуализировать историю большого проекта, у которого свой репозиторий, независимый от вашего проекта по его визуализации.  
+
При отсутствии известного системе логфайла, <tt>ShowTeamWork</tt> пытается вызвать скрипт <tt>getlog.py</tt>, где вы пропишете, что и откуда надо тянуть. Например, вы собираетесь визуализировать историю большого проекта, у которого свой репозиторий, независимый от вашего проекта по его визуализации, то надо как-то прописать, как вытащить лог этого проекта.
 +
 
 
<tt>getlog.py</tt> — [[Python]]-скрипт, он мультиплаформенный, в отличие от <tt>bat</tt>-файлов или <tt>shell</tt>-скриптов, и собственно не требует знания [[Python]]  — для всех проектов в подкаталоге <tt>samples</tt> есть скрипт <tt>getlog.py</tt>, так что при необходимости, просто скопируйте скрипт, вытаскивающий лог из нужной вам системы контроля версий (в каталоге <tt>samples</tt> представлены все поддерживаемые типы VCS).
 
<tt>getlog.py</tt> — [[Python]]-скрипт, он мультиплаформенный, в отличие от <tt>bat</tt>-файлов или <tt>shell</tt>-скриптов, и собственно не требует знания [[Python]]  — для всех проектов в подкаталоге <tt>samples</tt> есть скрипт <tt>getlog.py</tt>, так что при необходимости, просто скопируйте скрипт, вытаскивающий лог из нужной вам системы контроля версий (в каталоге <tt>samples</tt> представлены все поддерживаемые типы VCS).
  
Строка 306: Строка 330:
 
;comment: (необязательно) — комментарий
 
;comment: (необязательно) — комментарий
  
==Инсталляция ==
+
Кодировка — UTF-8, но если не подходит, пытается попробовать однобайтовые русскоязычные <tt>1251</tt>/<tt>koi-8</tt>.
  
Проект (исходники и бинарники) хостится на Google Code — http://code.google.com/p/showteamwork/.
+
=== stw-filter-events.py ===
  
Т.е. скомпилированные под Windows бинарники, вместе можно скачать [http://code.google.com/p/showteamwork/downloads/list отсюда],
+
В этом файле (по умолчанию будет сгенерирована «заготовка-рыба») определяется функция <tt>filter_events</tt>, которой передается объект <tt>event</tt>, с атрибутами, описанными [[#activity.xml|выше]], и которая возвращает
а если хотите поучаствовать в разработке — см. http://code.google.com/p/showteamwork/source/checkout
+
* <tt>True</tt>, если событие нужно обрабатывать, и
 +
* <tt>False</tt>, если событие  нужно игнорировать.
  
Единственное софтверное требование под Windows — наличие <tt>Java</tt> (все остальное идет в комплекте).
+
Для чего это нужно? Например, для того, чтобы обфускировать идентификаторы авторов или наоборот, восстанавливать, сводить несколько идентификаторов вида <tt>вася@дома</tt>, <tt><Василий Иванович Васильев> вася@office</tt> и <tt>вася@gmail</tt> к одному IDу <tt>вася</tt>.
 +
Для того, чтобы игнорировать некорректные входы (например даты из будущего — такое бывает).
  
Под Linux нужно установить (из исходников или пакетами — неважно):
+
Вот, к примеру фильтры для проекта <tt>bzr-svn</tt> — фильтруем события из будущего, сводим всех <tt>jelmer</tt> к одному, и для всех авторов пытаемся вытащить их email, выкинув ФИО и прочее:
* <tt>ffmpeg</tt>
+
<code-python>
* <tt>mencoder</tt> (из проекта <tt>mplayer</tt>)
+
def filter_events(event):
* <tt>python</tt> (для надежности версии 2.5 или 2.6).  
+
    # You can modify event attribute, or disable (filter) event, returning False
* <tt>gource</tt> http://code.google.com/p/gource/
+
    # Sample processing below
и сделать, чтобы эти утилиты были прописаны в путях.
+
    emailre_ = re.compile(r"(?P<email>[-a-z0-9_.]+@(?:[-a-z0-9\.]+))",
 +
                    re.IGNORECASE)
  
Cразу посмотрите каталог <tt>samples</tt>, должно быть все понятно.
+
    if event.date > time.time()*1000:
 +
      return False # Something wrong: event from future
  
Чуть позже, мы подробно распишем здесь назначение каждой настройки.
+
    if event.author.startswith("jelmer"):
 +
      event.author="jelmer@samba.org"     
 +
    event.author = event.author.lower().replace('"',"'")
 +
    m = emailre_.search(event.author)
 +
    if m:
 +
        event.author = m.group('email')
 +
    event.author = event.author.replace('"',"'")
 +
    if event.author in ["(no author)"]:
 +
        event.author = "anonymous"
 +
   
 +
    event.comment = re.sub('[Bb][Uu][Gg]\s*\d+\.?', '', event.comment)
 +
    if event.comment.startswith("*** empty log message ***"):
 +
        event.comment = ""
 +
 
 +
    if len(event.comment) < 10:
 +
        event.comment = ""
 +
 
 +
    return True
 +
</code-python>
 +
 
 +
 
 +
А также для «сведения» файловых путей (например, если CVS-репозиторий перемещался по файловой системе.
 +
Например, для вычисления истории PostgresQL, мы применяем следующий фильтр:
 +
<code-python>
 +
def filter_events(event):
 +
    prefixes=[
 +
        "/Users/neilc/postgres/cvs_root/",
 +
        "/home/projects/pgsql/cvsroot/",
 +
        "/projects/cvsroot/"
 +
    ]
 +
 
 +
    for p in prefixes:
 +
        if event.filename.startswith(p):
 +
          event.filename=event.filename.replace(p,"/")
 +
    return True
 +
</code-python>
 +
 
 +
 
 +
=== stw-scenario.txt ===
 +
Файл текстового «сценария» — история проекта в субтитрах.
 +
Строка начинающаяся с <tt>#</tt>, считается комментарием, остальные непустые строки
 +
состоят из даты и текста, разделенных пробелом[ами].
 +
;Дата: в формате <tt>%d.%m.%Y</tt> или <tt>%Y-%m-%d</tt>, как вам угодно.
 +
;Комментарий: простая текстовая строка в кодировке UTF-8.
 +
 
 +
По умолчанию, генерируется «заготовка-рыба» из событий, где для каждое первое появление нового участника пишется «Hi <участник>!», плюс закомментированная строка с лог-комментарием для каждого коммита — вы можете пройтись по тексту, выделить и раскомментировать ключевые события.
 +
 
 +
=== stw-config.py ===
 +
Основной файл настроек.
 +
 
 +
Он также представляет собой скрипт на [[Python]], в котором вы можете делать что угодно, главное — заполнить две строковых переменных
 +
;config: Собственно строка общей конфигурации, где перечислены настройки в формате «параметр=значение». Хотя большая часть настроек относиться только к <tt>Codeswarm</tt>-визуализации.
 +
Наиболее важными будут параметры раскраски (вы наверняка захотите поменять их), ведь только автор знает, какое деление по каталогам правильно (по умолчанию, цветовая карта создается для каталогов с наибольшей активностью, что конечно, не всегда правильно).
 +
Вот некоторый пример для визуализации Bugzilla — смысл, думаю понятен (метка, регэксп, ргб-цвет):
 +
  ColorAssign1="Attic",    "/cvsroot/mozilla/webtools/bugzilla/Attic.*",    255,242,146,  255,242,146
 +
  ColorAssign2="Bugzilla", "/cvsroot/mozilla/webtools/bugzilla/Bugzilla.*", 207,240,62,  207,240,62
 +
  ColorAssign3="docs",    "/cvsroot/mozilla/webtools/bugzilla/docs.*",    198,152,247,  198,152,247
 +
  ColorAssign4="template", "/cvsroot/mozilla/webtools/bugzilla/template.*", 6,195,37,    6,195,37
 +
  ColorAssign5="contrib",  "/cvsroot/mozilla/webtools/bugzilla/contrib.*",  132,120,49,  132,120,49
 +
  ColorAssign6="skins",    "/cvsroot/mozilla/webtools/bugzilla/skins.*",      9,115,81,    9,115,81
 +
 
 +
{{caution}} важно — нумеровать нужно последовательно, не пропуская цифр.
 +
 
 +
Из остальных, наиболее важных параметров, отметим следующие
 +
;Width: Ширина видео.
 +
;Height: Высота видео.
 +
;DrawNamesHalos: Рисовать гало вокруг меток (только для <tt>codeswarm</tt>).
 +
;ShowEdges: Показывать ли линии притяжения (только для <tt>codeswarm</tt>).
 +
 
 +
Для чего такие сложности? Просто генерация видео штука очень долгая, и сильно зависит от размера ролика.
 +
Поэтому, вы можете сначала сделать черновое видео маленького размера, и без спецэффектов, на котором обкатаете музыку, цвета,
 +
субтитры — и только потом, смените один символ, и сгенерируете видео высокого разрешения.
 +
Типичная часть из <tt>stw-config.py</tt> выглядит как-то так:
 +
<code-python>
 +
draft=0
 +
if draft:
 +
    config+="""
 +
Width=512
 +
Height=384
 +
DrawNamesHalos=false
 +
ShowEdges=false
 +
    """
 +
else:
 +
    config+="""
 +
Width=1280
 +
Height=800
 +
    """
 +
</code-python>
 +
 
 +
 
 +
;engine: Выбор типа визуализации и параметров, только для <tt>Codeswarm</tt>-визуализации.
 +
{{note}} Рекомендуем использовать только «PhysicsEngineSimple» визуализацию, как наиболее разумную (и не зависающую). Типичный набор параметров:
 +
# name of the engine class
 +
name=PhysicsEngineSimple
 +
 
 +
# parameters specific to this engine
 +
edgeMultiplier=1.0
 +
speedMultiplier=1.0
 +
nodesMultiplier=100.0
 +
drag=0.05
 +
 
 +
Тут наиболее интересен параметр <tt>nodesMultiplier</tt> — сила отталкивания элементов — если у вас все слишком далеко друг от друга, а лентяев вообще выкидывает к границе экрана — можете уменьшить, если все свалились в кучу — увеличивайте. За более детальными параметрами визуализации Codeswarm, обращайтесь к на [http://code.google.com/p/codeswarm/ страницу этого проекта].
 +
 
 +
Также в этом скрипте можно задать параметры:
 +
;GOURCE: Ненулевое значение — делать ролик с <tt>Gource</tt>-визуализацией. По умолчанию — делать.
 +
;CODESWARM: Ненулевое значение — делать ролик с <tt>CODESWARM</tt>-визуализацией. По умолчанию — делать.
 +
 
 +
В общем, см. примеры файлов <tt>stw-config.py</tt> в подкаталоге дистрибутива <tt>samples</tt>.
 +
 
 +
=== stw-audio.mp3 ===
 +
Музыкальный файл сопровождения.
 +
Если вы не предложите свой, будет взят случайный файл из подкаталога <tt>audio</tt>.
 +
 
 +
{{note}} Так что если у вас есть любимая коллекция музыки, и вы собираетесь визуализировать кучу проектов, не подбирая индивидуально звук для каждого проекта, просто залейте вашу коллекцию в подкаталог <tt>audio</tt>, оттуда <tt>mp3</tt>-файл будет выбираться случайно.
 +
 
 +
=== TemporaryCache ===
 +
Структуру временных файлов описывать специально не будем, отметим только, что все они лежат в
 +
вашем каталоге для временных файлов (под Windows он указан в переменной <tt>TEMP</tt>), в подкаталогах с префиксом <tt>STW-</tt> (кстати, они с атрибутами скрытых файлов под Windows).
 +
 
 +
Кстати, на диске с каталогом временных файлов может потребоваться немало места — размер зависит от проекта, но в целом, порядка нескольких гигабайт на проект.
 +
 
 +
Если у вас что-то как-то пошло не так (прервали генерацию, а потом, что-то как-то не так выглядит), или просто место понадобилось — можно очистить кеш, стерев эти каталоги.
  
 
== Контакты ==
 
== Контакты ==

Версия 20:49, 26 января 2010

Проблема

При грамотном процессе разработки, с применением средств групповой работы, таких, как:

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


Хочется:

  • эффективно извлечь из этих данных полезные знания:
Работа
кто, как и где «вкалывает»,
Взаимодействие
кто с кем, и в каких темах
например:
  • достаточно ли было Agile-кроссфункциональности?
  • где были проблемы (заброшенные области, забытые люди)
  • и т.п.
  • быстро и нескучно рассказать о работе своей команды:
    • демонстрации заказчикам;
    • гордость перед коллегами;
    • хедхантинг новых сотрудников.

Однако на практике возникает проблемы:

  • Question.svg как эффективно исследовать этот пласт информации?
  • Question.svg как эффектно показать свою работу лицом?

Question.svg Может посчитать метрики? Ненавистные SLOC и иже с ними? Да, такие инструменты есть:

В зависимости от глубины детализации можно получить:

    • либо пару унылых метрик («KSLOCs в месяц на сферического разработчика в вакууме», то есть в нашей метафоре максимум — «площадь лесного массива»)[1].
    • либо многостраничные Excel-dashboardы, заполненные мириадами цифр, в которых почти также бессмысленно лезть человеку, если он не профессор Чарли Эппс из сериала Numb3rs с его верными суперкомпьютерами и волшебными алгоритмами DataMining-a.

  • Читать логи переписки и коммиты в VCS?

No.svg То есть разрабатывать «шахту знаний» киркой и мотыгой? Бродить по лесу и считать деревья? Муторно!


Question.svg Что же делать?

Есть альтернативный способ «увидеть лес за деревьями» и при этом выжать краткую информацию по процессу — Визуализация. В динамике!

Есть уже даже несколько моделей!

Целых две ☻ .

Codeswarm

  • CodeSwarm.
  • Самая древняя! (год с копейками).
  • Визуализация физической модели «Люди и файлы» (на самом деле 4-ре модели: «Simple», «Chaotic», «Maxwell», «Legacy», но не все они «одинаково полезны», наиболее разумная — «Simple»).

Основная идея

    • «Люди» не любят друг друга — отталкиваются!
    • «Файлы» тоже отталкиваются! «обратно пропорционально расстоянию».
    • «Людей» и «Файлы» притягивает при коммитах!
    • «Люди» сближаются из-за совместной работы над одними файлами



А также:

  • Файлы можно красить (по директориям).
  • Работа красит — файлы красят людей.
  • Цветной пульс проекта в динамике.

Gource

Основная идея

  • Визуализация и структур каталогов («облака имен»)!
  • Модель «Пчелы» и «цветы»!
  • Видны:
    • «Горячие зоны».
    • Кроссфункциональные парни.
    • Заброшенные люди и код.



Что не хватает?

Important.svg Именно поэтому «самодельных» визуализаций — почти нет!

  • Сохраненного видео. Только рисует.
  • Какое видео без музыки?
  • Инфоканал — текст бегущей строкой — субтитры!
  • Максимальная автоматизация:
    • «старт с нуля» — только включить и дать на вход лог!
    • «эволюционные доработки» — легко и быстро «править кино».


Наш фреймворк ShowTeamWork

Important.svg Наше решение все это делает!

А именно:

  • Вытаскивается лог-информация, если запустить в workspace проекта под какой-нибудь из известных VCS — поддерживаются самые распространенные системы контроля версий: CVS, SVN, GIT, Bazaar, Mercurial (в принципе — можно визуализировать любую активность, хоть торговлю трейдеров).
  • Автоматически выбирается набор подкаталогов проекта с наибольшей активностью.
  • Для них генерируется случайная цветовая палитра, с взаимоконтрастными и яркими цветами.
  • При отсутствии «сценария субтитров» — генерируется шаблон-заготовка.
  • При отсутствии аудио сопровождения — предлагает заготовленную музыку в стиле «Ambient»
  • Порождает видео, с длительностью равной аудиозаписи, и накладывает субтитры, вычисляя их из формата «сценария субтитров», где события привязаны к датам.

Примеры

Альбом готовых визуализаций для известных софтверных проектов ( bugzilla, bzr-svn, codeswarm, ffmpeg, freemind, git, gource, inkscape, mediawiki, mercurial, mplayer, postgres, subversion, viewvc) можно посмотреть здесь.

Мы используем

Свободные, open-source программы:

А также несколько треков свободно доступной электронной музыки от Tunguska Music Society (License: Creative Commons). Если вы поленитесь искать музыку — мы сделаем клип на базе случайного трека (несколько треков идут в комплекте). Бесплатно и патриотично! Если хотите публиковать свои ролики, напоминаем о пока еще существующих цифровых правах на музыку и рекомендуем использовать только свободно доступную музыку — тут огромный выбор музыки в стиле Ambient.

Инсталляция

Проект (исходники и бинарники) хостится на Google Code — http://code.google.com/p/showteamwork/.

То есть скомпилированные под Windows бинарники, вместе можно скачать отсюда, а если хотите поучаствовать в разработке — см. http://code.google.com/p/showteamwork/source/checkout

Единственное софтверное требование под Windows — наличие Java (все остальное идет в комплекте).

Под Linux нужно установить (из исходников или пакетами — неважно):

и сделать, чтобы эти утилиты были прописаны в путях.

Cразу посмотрите каталог samples, должно быть все понятно.

Чуть позже, мы подробно распишем здесь назначение каждой настройки.


Быстрый старт

Caution.svg Для Windows-пользователей. Linux-пользователи, думаю, поймут сами, что и как.

Скачайте дистрибутив, распакуйте куда-нибудь его.


Зайдите в каталог проекта, то есть воркспейс под одной из систем контроля версий (CVS, SVN, GIT, Bazaar, Mercurial), причем не обязательно верхний уровень — можно на два-три уровня ниже, и вызовите showteamwork.exe, и отправляйтесь пить кофе.

В конце работы вы получите в каталоге, в котором его запустили пару видеофайлов (с codeswarm и gource визуализациями, по именам все будет понятно), а также вспомогательные файлы настроек и аудио, с префиксом stw-.

Далее, вы сможете редактировать эти файлы, подбирая оптимальные настройки, подходящую музыку, и редактируя историю проекта в субтитрах, и по окончании редактирования, перезапускайте showteamwork.exe.

Пересчет будет относительно экономичным — например, если вы меняли только параметры относящиеся к codeswarm-визуализации, то gource-визуализация пересчитыватся не будет, а если правили только субтитры — то будет выполнятся только наложение субтитров, без вызова gource или codeswarm.

Более детально, схема генерации описана ниже.

Схема генерации

Кликабельная (!) схема генерации:

[svg]

Упрощенная схема генерации представлена выше.

Note.svg Единственное необходимое — история проекта, в виде лог-файла, файла-генератора лог-файла, или просто workspace-проекта под одно из известных VCS, у которое лог-файл можно запросить.

Будучи запущенной ShowTeamWork без дополнительных файлов автоматически проанализирует лог, и

  • выделит наиболее «активные» каталоги
  • подберет для них случайную контрастную палитру цветов
  • сгенерирует файлы настроек
  • предложит одну из заготовленных[2] музыкальных дорожек в стиле Ambient.

А теперь поясним, зачем остальные сложности.

getlog.py

При отсутствии известного системе логфайла, ShowTeamWork пытается вызвать скрипт getlog.py, где вы пропишете, что и откуда надо тянуть. Например, вы собираетесь визуализировать историю большого проекта, у которого свой репозиторий, независимый от вашего проекта по его визуализации, то надо как-то прописать, как вытащить лог этого проекта.

getlog.pyPython-скрипт, он мультиплаформенный, в отличие от bat-файлов или shell-скриптов, и собственно не требует знания Python — для всех проектов в подкаталоге samples есть скрипт getlog.py, так что при необходимости, просто скопируйте скрипт, вытаскивающий лог из нужной вам системы контроля версий (в каталоге samples представлены все поддерживаемые типы VCS).

В скрипте, вы можете указать, например, параметры ограничивающие дату выборки лог-файла (например, только «последний спринт»).

import os
import datetime
 
begindate=(datetime.date.today()-datetime.timedelta(days=14)).strftime("%Y-%m-%d")
os.system(
"""
svn log --verbose --revision "{%(begindate)s}:HEAD" http://svn.wikimedia.org/svnroot/mediawiki/ >svn.log
""" % vars())

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

После работы этого скрипта, ожидается, что в каталоге будет один из следующих файлов:

cvs.log
получаемый командой
 cvs log
svn.log
получаемый командой
 svn log -v
bzr.log
получаемый командой
 bzr log -v
git.log
получаемый командой (без шуток и одной строкой):
git log --name-status  
    --pretty=format:"%n------------------------------------------------------------------------%nr%h | %ae | %ai (%aD) | x lines%nChanged paths:
hg.log
получаемый командой
 hg -v log
activity.xml
Стандартный XML-формат представления активности (см. #activity.xml).

Если getlog.py не обнаружено, или он не выдал ожидаемые лог-файлы, ShowTeamWork пытается получить их самостоятельно, ожидая, что ее запустили в каталоге проекта под какой-нибудь системой контроля версий. ShowTeamWork смотрит, нет ли одного из следующих подкаталогов (в каталоге запуска или на один-два уровня выше) CVS, .svn, .bzr, .git, .hg — и обнаружив таковой, пытается получить лог-файл от соответствующей системы контроля версий (должна быть установлена и «в путях»).

activity.xml

Стандартный XML-формат представления активности (когда, кто, с чем, что сделал):

<?xml version="1.0"?>
<file_events>
<event 
  date="1263155767000" 
  author="rotem"
  action="A"
  filename="/trunk/phase3/languages/messages/MessagesEn.php" 
  comment="Localization update for he, and whitespace fix in en.. " />
<event 
  date="1263155767000" 
  author="rotem"
  action="M"
  filename="/trunk/phase3/languages/messages/MessagesHe.php" 
  comment="Localization update for he, and whitespace fix in en.. " />
</file_events>

Т.е. все просто — последовательность event вложенных в file_events, а атрибуты event следующие:

date
Время события в миллисекундах от стандартной компьютерной эпохи (1970…).
author
Автор действия
filename
путь
action
(необязательно)
A
добавление
M
модификация
D
удаление
comment
(необязательно) — комментарий

Кодировка — UTF-8, но если не подходит, пытается попробовать однобайтовые русскоязычные 1251/koi-8.

stw-filter-events.py

В этом файле (по умолчанию будет сгенерирована «заготовка-рыба») определяется функция filter_events, которой передается объект event, с атрибутами, описанными выше, и которая возвращает

  • True, если событие нужно обрабатывать, и
  • False, если событие нужно игнорировать.

Для чего это нужно? Например, для того, чтобы обфускировать идентификаторы авторов или наоборот, восстанавливать, сводить несколько идентификаторов вида вася@дома, <Василий Иванович Васильев> вася@office и вася@gmail к одному IDу вася. Для того, чтобы игнорировать некорректные входы (например даты из будущего — такое бывает).

Вот, к примеру фильтры для проекта bzr-svn — фильтруем события из будущего, сводим всех jelmer к одному, и для всех авторов пытаемся вытащить их email, выкинув ФИО и прочее:

def filter_events(event):
    # You can modify event attribute, or disable (filter) event, returning False
    # Sample processing below
    emailre_ = re.compile(r"(?P<email>[-a-z0-9_.]+@(?:[-a-z0-9\.]+))",
                    re.IGNORECASE)
 
    if event.date > time.time()*1000:
       return False # Something wrong: event from future
 
    if event.author.startswith("jelmer"):
       event.author="jelmer@samba.org"      
    event.author = event.author.lower().replace('"',"'")
    m = emailre_.search(event.author)
    if m:
        event.author = m.group('email') 
    event.author = event.author.replace('"',"'")
    if event.author in ["(no author)"]:
        event.author = "anonymous"
 
    event.comment = re.sub('[Bb][Uu][Gg]\s*\d+\.?', '', event.comment)
    if event.comment.startswith("*** empty log message ***"):
        event.comment = ""
 
    if len(event.comment) < 10:
        event.comment = ""
 
    return True


А также для «сведения» файловых путей (например, если CVS-репозиторий перемещался по файловой системе. Например, для вычисления истории PostgresQL, мы применяем следующий фильтр:

def filter_events(event):
    prefixes=[
        "/Users/neilc/postgres/cvs_root/",
        "/home/projects/pgsql/cvsroot/",
        "/projects/cvsroot/"
    ]
 
    for p in prefixes:
        if event.filename.startswith(p):
           event.filename=event.filename.replace(p,"/") 
    return True


stw-scenario.txt

Файл текстового «сценария» — история проекта в субтитрах. Строка начинающаяся с #, считается комментарием, остальные непустые строки состоят из даты и текста, разделенных пробелом[ами].

Дата
в формате %d.%m.%Y или %Y-%m-%d, как вам угодно.
Комментарий
простая текстовая строка в кодировке UTF-8.

По умолчанию, генерируется «заготовка-рыба» из событий, где для каждое первое появление нового участника пишется «Hi <участник>!», плюс закомментированная строка с лог-комментарием для каждого коммита — вы можете пройтись по тексту, выделить и раскомментировать ключевые события.

stw-config.py

Основной файл настроек.

Он также представляет собой скрипт на Python, в котором вы можете делать что угодно, главное — заполнить две строковых переменных

config
Собственно строка общей конфигурации, где перечислены настройки в формате «параметр=значение». Хотя большая часть настроек относиться только к Codeswarm-визуализации.

Наиболее важными будут параметры раскраски (вы наверняка захотите поменять их), ведь только автор знает, какое деление по каталогам правильно (по умолчанию, цветовая карта создается для каталогов с наибольшей активностью, что конечно, не всегда правильно). Вот некоторый пример для визуализации Bugzilla — смысл, думаю понятен (метка, регэксп, ргб-цвет):

 ColorAssign1="Attic",    "/cvsroot/mozilla/webtools/bugzilla/Attic.*",    255,242,146,  255,242,146
 ColorAssign2="Bugzilla", "/cvsroot/mozilla/webtools/bugzilla/Bugzilla.*", 207,240,62,   207,240,62
 ColorAssign3="docs",     "/cvsroot/mozilla/webtools/bugzilla/docs.*",     198,152,247,  198,152,247
 ColorAssign4="template", "/cvsroot/mozilla/webtools/bugzilla/template.*", 6,195,37,     6,195,37
 ColorAssign5="contrib",  "/cvsroot/mozilla/webtools/bugzilla/contrib.*",   132,120,49,   132,120,49
 ColorAssign6="skins",    "/cvsroot/mozilla/webtools/bugzilla/skins.*",       9,115,81,     9,115,81 

Caution.svg важно — нумеровать нужно последовательно, не пропуская цифр.

Из остальных, наиболее важных параметров, отметим следующие

Width
Ширина видео.
Height
Высота видео.
DrawNamesHalos
Рисовать гало вокруг меток (только для codeswarm).
ShowEdges
Показывать ли линии притяжения (только для codeswarm).

Для чего такие сложности? Просто генерация видео штука очень долгая, и сильно зависит от размера ролика. Поэтому, вы можете сначала сделать черновое видео маленького размера, и без спецэффектов, на котором обкатаете музыку, цвета, субтитры — и только потом, смените один символ, и сгенерируете видео высокого разрешения. Типичная часть из stw-config.py выглядит как-то так:

draft=0
if draft:
    config+="""
Width=512
Height=384
DrawNamesHalos=false
ShowEdges=false
    """
else:
    config+="""
Width=1280
Height=800
    """


engine
Выбор типа визуализации и параметров, только для Codeswarm-визуализации.

Note.svg Рекомендуем использовать только «PhysicsEngineSimple» визуализацию, как наиболее разумную (и не зависающую). Типичный набор параметров:

# name of the engine class
name=PhysicsEngineSimple
# parameters specific to this engine
edgeMultiplier=1.0
speedMultiplier=1.0
nodesMultiplier=100.0
drag=0.05

Тут наиболее интересен параметр nodesMultiplier — сила отталкивания элементов — если у вас все слишком далеко друг от друга, а лентяев вообще выкидывает к границе экрана — можете уменьшить, если все свалились в кучу — увеличивайте. За более детальными параметрами визуализации Codeswarm, обращайтесь к на страницу этого проекта.

Также в этом скрипте можно задать параметры:

GOURCE
Ненулевое значение — делать ролик с Gource-визуализацией. По умолчанию — делать.
CODESWARM
Ненулевое значение — делать ролик с CODESWARM-визуализацией. По умолчанию — делать.

В общем, см. примеры файлов stw-config.py в подкаталоге дистрибутива samples.

stw-audio.mp3

Музыкальный файл сопровождения. Если вы не предложите свой, будет взят случайный файл из подкаталога audio.

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

TemporaryCache

Структуру временных файлов описывать специально не будем, отметим только, что все они лежат в вашем каталоге для временных файлов (под Windows он указан в переменной TEMP), в подкаталогах с префиксом STW- (кстати, они с атрибутами скрытых файлов под Windows).

Кстати, на диске с каталогом временных файлов может потребоваться немало места — размер зависит от проекта, но в целом, порядка нескольких гигабайт на проект.

Если у вас что-то как-то пошло не так (прервали генерацию, а потом, что-то как-то не так выглядит), или просто место понадобилось — можно очистить кеш, стерев эти каталоги.

Контакты


Резюме

  • Это забавная игрушка.
  • Пользоваться ей можно сходу, не приходя в сознание.
  • Но в ней куча настроек и прочих «степеней свободы» — подбор музыки, движка визулизации, параметров, палитры и т.п. — так что изготовление роликов визуализации более-менее искусство.
  • Результаты полезны для:
    • Рекламы проекта:
      • Представления проекта на конференции (очень сейчас модно, см. например выступление об проекте Debian Installer). У вас это займет всего минуты четыре, а аудитория проснется и заинтересуется.
      • Показа проекта без раскрытия кодов, при хедхантинге. Длинные, унылые, проекты с legacy-кодом будут даже смотреться интересней новых и перспективных проектов. И возможно тут предпочтительней использовать Codeswarm-визуализацию.
    • Показ работы в рамках SCRUM-демонстрации (или чего-то подобного), для донесения идеи — «мы тут вкалываем!» для заказчиков и прочих стейкхолдеров. Когда показывается короткая работа (неделя-месяц) — лучше использовать Gource-визуализацию.
  • Ну и полезно посмотреть на свой или чужой проект, для быстрого и целостного гештальт-восприятия (не затухает ли проект, сколько народу вкладывается в «ядре», и т.п.).

В принципе, наверное все сказано, на всякий случай, вдруг кому пригодится — короткий доклад о ShowTeamWorks на конференции AgileDays-2009 (особого ничего нового, по сравнению с написанным выше).

Примечания

  1. На самом деле сейчас уже есть интересные варианты с нетривиальной статической визуализацией SVN-репозиториев: SVNPlot, примеры: [1], [2]. Но в динамике все равно гораздо веселей.
  2. Свободный, выпущенных под лицензией Creative Commons

Любые правки этой статьи будут перезаписаны при следующем сеансе репликации. Если у вас есть серьезное замечание по тексту статьи, запишите его в раздел «discussion».

Репликация: База Знаний «Заказных Информ Систем» → «ShowTeamWork»