ShowTeamWork — различия между версиями
BenderBot (обсуждение | вклад) м (1 версия) |
|||
(не показаны 22 промежуточные версии 3 участников) | |||
Строка 1: | Строка 1: | ||
− | + | = Проблема = | |
При грамотном процессе разработки, с применением средств групповой работы, таких, как: | При грамотном процессе разработки, с применением средств групповой работы, таких, как: | ||
* трекеры задач ([[Bugzilla]], [[Jira]], [[Mantis]]), | * трекеры задач ([[Bugzilla]], [[Jira]], [[Mantis]]), | ||
Строка 25: | Строка 25: | ||
Однако на практике возникает проблемы: | Однако на практике возникает проблемы: | ||
− | + | {{question}} как {{good-words|эффективно исследовать}} этот пласт информации? | |
− | + | {{question}} как {{good-words|эффектно показать}} свою работу лицом? | |
---- | ---- | ||
Строка 33: | Строка 33: | ||
{{question}} Может посчитать {{bad-words|метрики}}? Ненавистные [[RuPedia:Количество_строк_кода|SLOC]] и иже с ними? | {{question}} Может посчитать {{bad-words|метрики}}? Ненавистные [[RuPedia:Количество_строк_кода|SLOC]] и иже с ними? | ||
Да, такие инструменты есть: | Да, такие инструменты есть: | ||
− | * [http://www.statsvn.org/ StatSVN] Примеры: [http://www.statsvn.org/demo/continuum/], [http://www.statsvn.org/demo/jodatime/], [http://www.statsvn.org/demo/ruby/], [http://www.statsvn.org/demo/ant/], [http://www.statsvn.org/demo/synapse/], [http://www.statsvn.org/demo/synapse/], [http://www.statsvn.org/demo/qalab/],… | + | * [http://www.statsvn.org/ StatSVN]. Примеры: [http://www.statsvn.org/demo/continuum/], [http://www.statsvn.org/demo/jodatime/], [http://www.statsvn.org/demo/ruby/], [http://www.statsvn.org/demo/ant/], [http://www.statsvn.org/demo/synapse/], [http://www.statsvn.org/demo/synapse/], [http://www.statsvn.org/demo/qalab/],… |
В зависимости от глубины детализации можно получить: | В зависимости от глубины детализации можно получить: | ||
− | + | * либо пару унылых метрик («KSLOCs в месяц на сферического разработчика в вакууме», то есть в нашей метафоре максимум — «площадь лесного массива»)<ref>На самом деле сейчас уже есть интересные варианты с | |
нетривиальной статической визуализацией SVN-репозиториев: [http://code.google.com/p/svnplot/ SVNPlot], примеры: [http://thinkingcraftsman.in/projects/sna_subversion/sna_subversion.htm], [http://svnplot.googlecode.com/svn/trunk/examples/centralitytreemap/centralitytreemap.htm]. Но в динамике все равно гораздо веселей.</ref>. | нетривиальной статической визуализацией SVN-репозиториев: [http://code.google.com/p/svnplot/ SVNPlot], примеры: [http://thinkingcraftsman.in/projects/sna_subversion/sna_subversion.htm], [http://svnplot.googlecode.com/svn/trunk/examples/centralitytreemap/centralitytreemap.htm]. Но в динамике все равно гораздо веселей.</ref>. | ||
− | + | * либо многостраничные Excel-dashboardы, заполненные мириадами цифр, в которых почти также бессмысленно лезть человеку, ''если он не профессор Чарли Эппс из сериала Numb3rs с его верными суперкомпьютерами и волшебными алгоритмами DataMining-a''. | |
---- | ---- | ||
− | + | {{question}} Читать логи переписки и коммиты в VCS? | |
{{no}} То есть разрабатывать «шахту знаний» киркой и мотыгой? Бродить по лесу и считать деревья? {{bad-words|Муторно}}! | {{no}} То есть разрабатывать «шахту знаний» киркой и мотыгой? Бродить по лесу и считать деревья? {{bad-words|Муторно}}! | ||
Строка 50: | Строка 50: | ||
Есть альтернативный способ «увидеть лес за деревьями» и при этом выжать краткую информацию по процессу — {{good-words|Визуализация}}. В {{good-words|динамике}}! | Есть альтернативный способ «увидеть лес за деревьями» и при этом выжать краткую информацию по процессу — {{good-words|Визуализация}}. В {{good-words|динамике}}! | ||
+ | |||
+ | = Визуализация = | ||
Есть уже даже несколько моделей! | Есть уже даже несколько моделей! | ||
Строка 59: | Строка 61: | ||
* [http://code.google.com/p/codeswarm/ CodeSwarm]. | * [http://code.google.com/p/codeswarm/ CodeSwarm]. | ||
* {{good-words|Самая древняя!}} (год с копейками). | * {{good-words|Самая древняя!}} (год с копейками). | ||
− | * Визуализация физической модели {{good-words|«Люди и файлы»}} (на самом деле '''4'''-ре модели: «Simple», «Chaotic», «Maxwell», «Legacy»). | + | * Визуализация физической модели {{good-words|«Люди и файлы»}} (на самом деле '''4'''-ре модели: «Simple», «Chaotic», «Maxwell», «Legacy», но не все они «одинаково полезны», наиболее разумная — «Simple»). |
=== Основная идея === | === Основная идея === | ||
− | + | * «Люди» не любят друг друга — {{bad-words|отталкиваются!}} | |
− | + | * «Файлы» тоже {{bad-words|отталкиваются!}} «обратно пропорционально расстоянию». | |
− | + | * «Людей» и «Файлы» {{good-words|притягивает при коммитах}}! | |
− | + | * «Люди» {{good-words|сближаются из-за совместной работы}} над одними файлами | |
Строка 75: | Строка 77: | ||
* Цветной пульс проекта в динамике. | * Цветной пульс проекта в динамике. | ||
− | === | + | {{vimeoembed|9085962|640|640}} |
− | {{ | + | |
+ | == Gource == | ||
+ | === Основная идея === | ||
+ | |||
+ | * Визуализация и {{good-words|структур каталогов}} («облака имен»)! | ||
+ | * Модель {{good-words|«Пчелы» и «цветы»}}! | ||
+ | |||
+ | Видны: | ||
+ | * «Горячие зоны». | ||
+ | * {{good-words|Кроссфункциональные}} парни. | ||
+ | * {{bad-words|Заброшенные}} люди и код. | ||
+ | |||
+ | {{vimeoembed|8758085|640|640}} | ||
+ | |||
+ | == Что не хватает? == | ||
* Сохраненного {{good-words|видео}}. Только {{bad-words|рисует}}. | * Сохраненного {{good-words|видео}}. Только {{bad-words|рисует}}. | ||
Строка 85: | Строка 101: | ||
** {{good-words|«эволюционные доработки»}} — легко и быстро «править кино». | ** {{good-words|«эволюционные доработки»}} — легко и быстро «править кино». | ||
− | {{important}} | + | {{important}} Именно поэтому «самодельных» {{bad-words|визуализаций — почти нет}}! |
− | |||
− | = | + | = Наш фреймворк ShowTeamWork= |
− | + | {{important}} Наше решение {{good-words|все это делает}}! | |
− | + | ||
− | + | ||
− | + | ||
− | + | А именно: | |
+ | * Вытаскивается лог-информация, если запустить в ''workspace'' проекта под какой-нибудь из известных VCS — поддерживаются самые распространенные системы контроля версий: <tt>CVS</tt>, <tt>SVN</tt>, <tt>GIT</tt>, <tt>Bazaar</tt>, <tt>Mercurial</tt> (в принципе — можно визуализировать любую активность, хоть торговлю трейдеров). | ||
+ | * Автоматически выбирается набор подкаталогов проекта с наибольшей активностью. | ||
+ | * Для них генерируется случайная цветовая палитра, с взаимоконтрастными и яркими цветами. | ||
+ | * При отсутствии «сценария субтитров» — генерируется шаблон-заготовка. | ||
+ | * При отсутствии аудио сопровождения — предлагает заготовленную музыку в стиле «Ambient» | ||
+ | * Порождает видео, с длительностью равной аудиозаписи, и накладывает субтитры, вычисляя их из формата «сценария субтитров», где события привязаны к датам. | ||
− | == | + | == Примеры == |
− | + | Альбом готовых визуализаций для известных софтверных проектов ( | |
+ | <tt>bugzilla</tt>, | ||
+ | <tt>bzr-svn</tt>, | ||
+ | <tt>codeswarm</tt>, | ||
+ | <tt>ffmpeg</tt>, | ||
+ | <tt>freemind</tt>, | ||
+ | <tt>git</tt>, | ||
+ | <tt>gource</tt>, | ||
+ | <tt>inkscape</tt>, | ||
+ | <tt>mediawiki</tt>, | ||
+ | <tt>mercurial</tt>, | ||
+ | <tt>mplayer</tt>, | ||
+ | <tt>postgres</tt>, | ||
+ | <tt>subversion</tt>, | ||
+ | <tt>viewvc</tt>) можно посмотреть [http://vimeo.com/album/160744 здесь]. | ||
+ | |||
+ | == Мы используем == | ||
Свободные, ''open-source'' программы: | Свободные, ''open-source'' программы: | ||
− | * [http://code.google.com/p/codeswarm/ CodeSwarm] (GPLv3). | + | * [http://code.google.com/p/codeswarm/ <tt>CodeSwarm</tt>] (<tt>GPLv3</tt>) (требует установленной <tt>Java</tt>, версии не меньше <tt>1.6</tt>). |
− | * [http://code.google.com/p/gource/ Gource] (GPLv3). | + | * [http://code.google.com/p/gource/ <tt>Gource</tt>] (<tt>GPLv3</tt>). |
− | * [http://www.mplayerhq.hu/ MEncoder] ( | + | * [http://www.mplayerhq.hu/ <tt>MEncoder</tt>] (<tt>GPLv2</tt>). |
− | * [http://ffmpeg.org/ FFmpeg] (LGPL | + | * [http://ffmpeg.org/ <tt>FFmpeg</tt>] (<tt>LGPL</tt> или <tt>GPL</tt>). |
− | А также несколько треков свободно доступной электронной музыки от [http://tunguskagrooves.com/ Tunguska Music Society] (License: Creative Commons). | + | А также несколько треков свободно доступной электронной музыки от [http://tunguskagrooves.com/ Tunguska Music Society] (<tt>License: Creative Commons</tt>). |
Если вы поленитесь искать музыку — мы сделаем клип на базе случайного трека (несколько треков идут в комплекте). | Если вы поленитесь искать музыку — мы сделаем клип на базе случайного трека (несколько треков идут в комплекте). | ||
Бесплатно и патриотично! | Бесплатно и патриотично! | ||
Если хотите публиковать свои ролики, напоминаем о пока еще существующих цифровых правах на музыку и рекомендуем использовать только свободно доступную музыку — [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>, должно быть все понятно. | ||
+ | |||
+ | Чуть позже, мы подробно распишем здесь назначение каждой настройки. | ||
+ | |||
+ | |||
+ | == Быстрый старт == | ||
+ | |||
+ | {{caution}} Для Windows-пользователей. Linux-пользователи, думаю, поймут сами, что и как. | ||
+ | |||
+ | Скачайте [http://code.google.com/p/showteamwork/downloads/ дистрибутив], распакуйте куда-нибудь его. | ||
+ | Зайдите в каталог проекта, то есть воркспейс под одной из систем контроля версий (<tt>CVS</tt>, <tt>SVN</tt>, <tt>GIT</tt>, <tt>Bazaar</tt>, <tt>Mercurial</tt>), причем не обязательно верхний уровень — можно на два-три уровня ниже, и вызовите | ||
+ | <tt>showteamwork.exe</tt>, и отправляйтесь пить кофе. | ||
+ | |||
+ | В конце работы вы получите в каталоге, в котором его запустили пару видеофайлов (с <tt>codeswarm</tt> и <tt>gource</tt> визуализациями, по именам все будет понятно), а также вспомогательные файлы настроек и аудио, с префиксом <tt>stw-</tt>. | ||
+ | |||
+ | Далее, вы сможете редактировать эти файлы, подбирая оптимальные настройки, подходящую музыку, и редактируя историю проекта в субтитрах, и по окончании редактирования, перезапускайте <tt>showteamwork.exe</tt>. | ||
+ | |||
+ | Пересчет будет относительно экономичным — например, если вы меняли только параметры относящиеся к <tt>codeswarm</tt>-визуализации, то <tt>gource</tt>-визуализация пересчитыватся не будет, а если правили только субтитры — то будет выполнятся только наложение субтитров, без вызова <tt>gource</tt> или <tt>codeswarm</tt>. | ||
+ | |||
+ | Более детально, схема генерации описана ниже. | ||
+ | |||
+ | == Схема генерации == | ||
+ | |||
+ | Кликабельная (!) схема генерации: | ||
<graph> | <graph> | ||
digraph G{ | digraph G{ | ||
− | rankdir= | + | rankdir=TB |
+ | |||
+ | edge [color=blue] | ||
+ | |||
node [style=filled shape=note] | node [style=filled shape=note] | ||
− | " | + | node [fillcolor="goldenrod1" shape=box3d] |
+ | workspace [label="Workspaсe-каталог \n под VCS" shape=folder] | ||
+ | svcslog [label="Входной лог-файл: \n cvs.log, svn-log.xml, git.log, \n bzr.log, hg.log, activity.xml"] | ||
+ | getlog [label="Генератор лога: \n «getlog.py»" URL="#getlog.py"] | ||
− | + | ||
− | + | ||
− | + | ||
+ | node [fillcolor=aliceblue shape=note] | ||
+ | |||
+ | svcslog -> vcslog0 | ||
+ | vcslog0 -> vcslog [label="есть"] | ||
+ | vcslog1 -> vcslog [label="есть"] | ||
+ | vcslog2 -> vcslog [label="есть"] | ||
+ | vcslog0 -> vcslog1 -> vcslog2 [label="нет" color=red] | ||
+ | getlog -> vcslog1 | ||
+ | workspace -> vcslog2 | ||
+ | |||
+ | vcslog0 [label="лог-файл"] | ||
+ | vcslog1 [label="лог-файл"] | ||
+ | vcslog2 [label="лог-файл"] | ||
+ | vcslog [label="Лог-файл: \n cvs.log, svn-log.xml, git.log, \n bzr.log, hg.log, activity.xml"] | ||
+ | |||
+ | node [fillcolor="#0084FF" shape=egg fontcolor=yellow] | ||
+ | scenario [label="История \n stw-scenario.txt" URL="#stw-scenario.txt"] | ||
+ | audio [label="Музыка \n stw-audio.mp3" URL="#stw-audio.mp3"] | ||
+ | config [label="Настройки \n stw-config.py" URL="#stw-config.py"] | ||
+ | filters [label="Фильтры \n stw-filter-events.py " URL="#stw-filter-events.py"] | ||
+ | |||
+ | activity [label="Обработанная \n активность\n activity.xml" URL="#activity.xml"] | ||
+ | |||
+ | filters -> activity | ||
+ | vcslog -> activity | ||
+ | |||
+ | cache [label="Кеш-данные" URL="#TemporaryCache"] | ||
+ | |||
+ | node [fontcolor=black] | ||
+ | "Визуализация" [fillcolor=yellow shape=diamond] | ||
+ | audio -> "Визуализация" [label="Задает \n длительность"] | ||
+ | config -> "Визуализация" [label="Настройки \n визуализации"] | ||
+ | activity -> "Визуализация" | ||
+ | |||
+ | "Визуализация" -> cache | ||
+ | |||
+ | |||
+ | scenario -> "Субтитры" | ||
+ | audio -> "Субтитры" [label="Задает \n длительность"] | ||
+ | |||
+ | "Субтитры" -> result | ||
+ | cache -> result | ||
+ | |||
+ | result [label="Результат: \n project-codeswarm-xxx.avi \n project-gource-yyy.avi" fillcolor=gold shape=house] | ||
} | } | ||
</graph> | </graph> | ||
+ | |||
+ | Упрощенная схема генерации представлена выше. | ||
+ | |||
+ | {{note}} Единственное необходимое — история проекта, в виде лог-файла, файла-генератора лог-файла, или просто ''workspace''-проекта под одно из известных VCS, у которое лог-файл можно запросить. | ||
+ | |||
+ | Будучи запущенной <tt>ShowTeamWork</tt> без дополнительных файлов автоматически проанализирует лог, и | ||
+ | * выделит наиболее «активные» каталоги | ||
+ | * подберет для них случайную контрастную палитру цветов | ||
+ | * сгенерирует файлы настроек | ||
+ | * предложит одну из заготовленных<ref>Свободный, выпущенных под лицензией Creative Commons</ref> музыкальных дорожек в стиле ''Ambient''. | ||
+ | |||
+ | А теперь поясним, зачем остальные сложности. | ||
+ | |||
+ | == getlog.py == | ||
+ | При отсутствии известного системе логфайла, <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). | ||
+ | |||
+ | В скрипте, вы можете указать, например, параметры ограничивающие дату выборки лог-файла (например, только «последний спринт»). | ||
+ | |||
+ | <code-python> | ||
+ | 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()) | ||
+ | </code-python> | ||
+ | |||
+ | Или вы можете написать свой скрипт, который, например, будет доставать данные из вики-системы, трекера-задач, системы документооборота или любой системы, подразумевающей командную работу. | ||
+ | |||
+ | После работы этого скрипта, ожидается, что в каталоге будет один из следующих файлов: | ||
+ | |||
+ | ;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]]). | ||
+ | |||
+ | Если <tt>getlog.py</tt> не обнаружено, или он не выдал ожидаемые лог-файлы, | ||
+ | <tt>ShowTeamWork</tt> пытается получить их самостоятельно, ожидая, что ее запустили в каталоге проекта под какой-нибудь системой контроля версий. | ||
+ | <tt>ShowTeamWork</tt> смотрит, нет ли одного из следующих подкаталогов (в каталоге запуска или на один-два уровня выше) | ||
+ | <tt>CVS</tt>, <tt>.svn</tt>, <tt>.bzr</tt>, <tt>.git</tt>, <tt>.hg</tt> — и обнаружив таковой, пытается получить лог-файл от соответствующей системы контроля версий (должна быть установлена и «в путях»). | ||
+ | |||
+ | == activity.xml == | ||
+ | |||
+ | Стандартный XML-формат представления активности (когда, кто, с чем, что сделал): | ||
+ | <code-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> | ||
+ | </code-xml> | ||
+ | |||
+ | Т.е. все просто — последовательность <tt>event</tt> вложенных в <tt>file_events</tt>, а атрибуты | ||
+ | <tt>event</tt> следующие: | ||
+ | ;date: Время события в миллисекундах от стандартной компьютерной эпохи (1970…). | ||
+ | ;author: Автор действия | ||
+ | ;filename: путь | ||
+ | ;action: (необязательно) | ||
+ | :;A: добавление | ||
+ | :;M: модификация | ||
+ | :;D: удаление | ||
+ | ;comment: (необязательно) — комментарий | ||
+ | |||
+ | Кодировка — UTF-8, но если не подходит, пытается попробовать однобайтовые русскоязычные <tt>1251</tt>/<tt>koi-8</tt>. | ||
+ | |||
+ | == stw-filter-events.py == | ||
+ | |||
+ | В этом файле (по умолчанию будет сгенерирована «заготовка-рыба») определяется функция <tt>filter_events</tt>, которой передается объект <tt>event</tt>, с атрибутами, описанными [[#activity.xml|выше]], и которая возвращает | ||
+ | * <tt>True</tt>, если событие нужно обрабатывать, и | ||
+ | * <tt>False</tt>, если событие нужно игнорировать. | ||
+ | |||
+ | Для чего это нужно? Например, для того, чтобы обфускировать идентификаторы авторов или наоборот, восстанавливать, сводить несколько идентификаторов вида <tt>вася@дома</tt>, <tt><Василий Иванович Васильев> вася@office</tt> и <tt>вася@gmail</tt> к одному IDу <tt>вася</tt>. | ||
+ | Для того, чтобы игнорировать некорректные входы (например даты из будущего — такое бывает). | ||
+ | |||
+ | Вот, к примеру фильтры для проекта <tt>bzr-svn</tt> — фильтруем события из будущего, сводим всех <tt>jelmer</tt> к одному, и для всех авторов пытаемся вытащить их email, выкинув ФИО и прочее: | ||
+ | <code-python> | ||
+ | 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 | ||
+ | </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). | ||
+ | |||
+ | Кстати, на диске с каталогом временных файлов может потребоваться немало места — размер зависит от проекта, но в целом, порядка нескольких гигабайт на проект. | ||
+ | |||
+ | Если у вас что-то как-то пошло не так (прервали генерацию, а потом, что-то как-то не так выглядит), или просто место понадобилось — можно очистить кеш, стерев эти каталоги. | ||
+ | |||
+ | == Контакты == | ||
+ | |||
+ | Все баги, пожелания и предложения, пожалуйста [http://code.google.com/p/showteamwork/issues/list сюда]. | ||
+ | Ну, на худой конец, обращайтесь на прямую — все мои контакты: [http://belonesox.moikrug.ru Стас Фомин]. | ||
+ | |||
+ | = Резюме = | ||
+ | |||
+ | * Это забавная игрушка. | ||
+ | * Пользоваться ей можно сходу, не приходя в сознание. | ||
+ | * Но в ней куча настроек и прочих «степеней свободы» — подбор музыки, движка визулизации, параметров, палитры и т.п. — так что изготовление роликов визуализации более-менее искусство. | ||
+ | |||
+ | Результаты полезны для: | ||
+ | * Рекламы проекта: | ||
+ | ** Представления проекта на конференции (очень сейчас модно, см. например [http://vimeo.com/6553097 выступление об проекте Debian Installer]). У вас это займет всего минуты четыре, а аудитория проснется и заинтересуется. | ||
+ | ** Показа проекта без раскрытия кодов, при хедхантинге. Длинные, унылые, проекты с ''legacy''-кодом будут даже смотреться интересней новых и перспективных проектов. И возможно тут предпочтительней использовать <tt>Codeswarm</tt>-визуализацию. | ||
+ | * Показ работы в рамках <tt>SCRUM</tt>-демонстрации (или чего-то подобного), для донесения идеи — «мы тут вкалываем!» для заказчиков и прочих стейкхолдеров. Когда показывается короткая работа (неделя-месяц) — лучше использовать <tt>Gource</tt>-визуализацию. | ||
+ | * Ну и полезно посмотреть на свой или чужой проект, для быстрого и целостного гештальт-восприятия (не затухает ли проект, сколько народу вкладывается в «ядре», и т.п.). | ||
+ | |||
+ | В принципе, наверное все сказано, на всякий случай, вдруг кому пригодится — короткий доклад о [[ShowTeamWork]] на [[AgileDays-2009_(Technical_excelence)|конференции AgileDays-2009]] (особого ничего нового, по сравнению с написанным выше). | ||
+ | {{vimeoembed|8246851|640|512}} | ||
+ | |||
+ | |||
+ | == Проблемы и ToDo == | ||
+ | * Есть две версии <tt>ffmpeg</tt>, с одной STW пока не совместим (проблема только под <tt>Linux</tt>). | ||
+ | * <tt>Gource</tt> делает нелинейную визуализацию (время в визуализации течет нелинейно), игнорирует параметры исторического времени (<tt>--seconds-per-day</tt>) и визуализации. За пару часов под Windows/MinGW собрать его не удалось, буду разбираться когда руки дойдут. | ||
+ | * <tt>Gource</tt> требует много места на винчестере под временные файлы (ибо под Windows он не умеет передавать видеопоток через пайп или другой аналог, и приходится записывать непакованное видео). | ||
+ | * Мне не ясно, как из <tt>Mercurial</tt>-лога вытащить информацию о типе изменения («добавление», «правка», «удаление»), чтобы корректно показать это в <tt>Gource</tt>. | ||
+ | * <tt>Codeswarm</tt> часто зависает при использовании <tt>PhysicsEngineChaotic</tt>. Не используйте пока эту модель. Поставлен [http://code.google.com/p/codeswarm/issues/detail?id=67 баг] разработчику. | ||
+ | * Описание на английском. | ||
+ | |||
+ | == Примечания == | ||
+ | <references/> | ||
{{replicate-from-custiswiki-to-lib}} | {{replicate-from-custiswiki-to-lib}} | ||
+ | {{replicate-from-custiswiki-to-4intranet}} |
Текущая версия на 17:53, 5 апреля 2012
Проблема
При грамотном процессе разработки, с применением средств групповой работы, таких, как:
- трекеры задач (Bugzilla, Jira, Mantis),
- вики-системы (CustisWiki) и
- системы контроля версий (CVS, Subversion, git, Mercurial, Bazaar ),
накапливается огромная история коллективного взаимодействия команды.
Хочется:
- эффективно извлечь из этих данных полезные знания:
- Работа
- кто, как и где «вкалывает»,
- Взаимодействие
- кто с кем, и в каких темах
- например:
- достаточно ли было Agile-кроссфункциональности?
- где были проблемы (заброшенные области, забытые люди)
- и т.п.
- быстро и нескучно рассказать о работе своей команды:
- демонстрации заказчикам;
- гордость перед коллегами;
- хедхантинг новых сотрудников.
Однако на практике возникает проблемы:
как эффективно исследовать этот пласт информации?
как эффектно показать свою работу лицом?
Может посчитать метрики? Ненавистные SLOC и иже с ними?
Да, такие инструменты есть:
В зависимости от глубины детализации можно получить:
- либо пару унылых метрик («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. Не используйте пока эту модель. Поставлен баг разработчику.
- Описание на английском.
Примечания
- ↑ На самом деле сейчас уже есть интересные варианты с нетривиальной статической визуализацией SVN-репозиториев: SVNPlot, примеры: [1], [2]. Но в динамике все равно гораздо веселей.
- ↑ Свободный, выпущенных под лицензией Creative Commons
Любые правки этой статьи будут перезаписаны при следующем сеансе репликации. Если у вас есть серьезное замечание по тексту статьи, запишите его в раздел «discussion».
Репликация: База Знаний «Заказных Информ Систем» → «ShowTeamWork»
Статья реплицируется в Wiki4IntraNet.