Текущая версия на 17:53, 5 апреля 2012

Проблема

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

• трекеры задач (Bugzilla, Jira, Mantis),
• вики-системы (CustisWiki) и
• системы контроля версий (CVS, Subversion, git, Mercurial, Bazaar ),

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

Хочется:

• эффективно извлечь из этих данных полезные знания:

Работа

кто, как и где «вкалывает»,

Взаимодействие

кто с кем, и в каких темах

например:

• достаточно ли было Agile-кроссфункциональности?
• где были проблемы (заброшенные области, забытые люди)
• и т.п.

• быстро и нескучно рассказать о работе своей команды:
  • демонстрации заказчикам;
  • гордость перед коллегами;
  • хедхантинг новых сотрудников.

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

как эффективно исследовать этот пласт информации?

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

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

• StatSVN. Примеры: [3], [4], [5], [6], [7], [8], [9],…

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

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

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

Что же делать?

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

Визуализация

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

Целых две ☻ .

Codeswarm

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

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

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

А также:

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

Gource

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

• Визуализация и структур каталогов («облака имен»)!
• Модель «Пчелы» и «цветы»!

Видны:

• «Горячие зоны».
• Кроссфункциональные парни.
• Заброшенные люди и код.

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

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

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

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

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

А именно:

• Вытаскивается лог-информация, если запустить в 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 программы:

• CodeSwarm (GPLv3) (требует установленной Java, версии не меньше 1.6).
• Gource (GPLv3).
• MEncoder (GPLv2).
• FFmpeg (LGPL или GPL).

А также несколько треков свободно доступной электронной музыки от 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 нужно установить (из исходников или пакетами — неважно):

• ffmpeg
• mencoder (из проекта mplayer)
• python (для надежности версии 2.5 или 2.6).
• gource http://code.google.com/p/gource/

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

getlog.py

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

getlog.py — Python-скрипт, он мультиплаформенный, в отличие от 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  --xml --verbose --revision "{%(begindate)s}:HEAD" http://svn.wikimedia.org/svnroot/mediawiki/ >svn-log.xml
""" % vars())

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

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

cvs.log

получаемый командой

 cvs log

svn-log.xml

получаемый командой

 svn log --xml --verbose

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 

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

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

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-визуализации.

Рекомендуем использовать только «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.

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

TemporaryCache

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

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

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

Контакты

Все баги, пожелания и предложения, пожалуйста сюда. Ну, на худой конец, обращайтесь на прямую — все мои контакты: Стас Фомин.

Резюме

• Это забавная игрушка.
• Пользоваться ей можно сходу, не приходя в сознание.
• Но в ней куча настроек и прочих «степеней свободы» — подбор музыки, движка визулизации, параметров, палитры и т.п. — так что изготовление роликов визуализации более-менее искусство.

Результаты полезны для:

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

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

Проблемы и ToDo

• Есть две версии ffmpeg, с одной STW пока не совместим (проблема только под Linux).
• Gource делает нелинейную визуализацию (время в визуализации течет нелинейно), игнорирует параметры исторического времени (--seconds-per-day) и визуализации. За пару часов под Windows/MinGW собрать его не удалось, буду разбираться когда руки дойдут.
• Gource требует много места на винчестере под временные файлы (ибо под Windows он не умеет передавать видеопоток через пайп или другой аналог, и приходится записывать непакованное видео).
• Мне не ясно, как из Mercurial-лога вытащить информацию о типе изменения («добавление», «правка», «удаление»), чтобы корректно показать это в Gource.
• Codeswarm часто зависает при использовании PhysicsEngineChaotic. Не используйте пока эту модель. Поставлен баг разработчику.
• Описание на английском.

Примечания

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

Внимание! Данная статья выбрана для репликации во внешнюю базу знаний компании. Пожалуйста, не допускайте в этой статье публикацию конфиденциальной информации, ведения обсуждений в теле статьи, и более ответственно относитесь к качеству самой статьи — проверяйте орфографию, пишите по-русски, избегайте непроверенной вами информации.