Git, Github, управление версиями и вы

19.08.2015

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

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

Мы не только можем исследовать бесконечное разнообразие программного обеспечения, мы можем также совместно работать с людьми в различных часовых поясах, в различных частях мира, и всё это, не говоря им ни единого слова (хотя я настоятельно рекомендую наладить хорошие коммуникации со стоящими соавторами). Когда вы создаёте общедоступное место для выкладки файлов проекта программы, опишите чёткие задачи, которые должны быть выполнены, и любой, кто имеет доступ, сможет их выполнять и применять (коммитить) свои изменения в репозитории. Соавторы помогают вам развивать проект без необходимости отправлять флоппи-диски почтой по кругу.

Как хранить проекты программ, публично или приватно

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

Github предлагает два основных варианта: вы можете загружать исходные файлы публично и использовать их инструменты и дисковое пространство бесплатно, или вы можете платить вместо этого небольшие деньги, чтобы сохранить свой исходный код приватно, с доступом только для вас и вашей группы. Вы должны определить, согласны ли с Условиями пользования сервисом, но при этом учтите, что всё больше разработчиков используют Github как место для хранения своей работы. Если сделаете свои файлы публичными на Github, то любой сможет клонировать копию вашего проекта, но если для вас это нормально – продолжайте и наслаждайтесь открытостью.

К счастью, вы не должны быть классическим разработчиком программного обеспечения, чтобы использовать Github. Писатели также часто работают в Markdown, HTML или каком-либо другом текстовом формате, сохраняют свои файлы в репозиториях Github.

Моя философия, которую придумал не я, но которая становится всё более распространённой, заключается в том, что документация и исходный код должны жить вместе в одном и том же репозитории. Часто документы и исходный код связаны друг с другом, например, через контекстно-зависимую справку. Но держать даже автономную документацию в том же месте, где находятся и другие файлы проекта, всё же имеет смысл. Исходный код не требуется — вы можете так же просто разместить на Github свой роман, созданный по модели краудсорсинга, даже если за ним совсем нет исходного кода.

Github — это не единственный сайт, где можно хранить проекты. Вы можете посмотреть в сторону bitbucket.org, поддерживаемый компанией Atlassian, возможно, он вам подойдёт лучше.

Github и git

Hadoop — это фреймворк первостепенного значения в мире больших данных, и его открытый исходный код доступен на Github для всех, кто хочет «раскрутить» его.

Git, программа управления версиями, разработанная для открытого проекта Linux, обеспечивает работу Github и возникла раньше него на много лет. С помощью git любой пользователь может клонировать ваш репозиторий и затем делать что угодно с копией ваших файлов. Однако ваш исходный репозиторий остаётся нетронутым, пока вы не согласитесь применить в исходном репозитории изменения. Git касается процесса выкладки изменений в репозитории в виде запросов на применение изменений (pull request).

Если вы технический писатель, у которого голова кругом идёт от использования git и Github, то я настоятельно рекомендую учебные пособия, которые разработала Сара Кинири (Sarah Kiniry): http://technicolorwriter.com/why-agile-writers-need-to-use-git/.

Если вы следуете философии хранения документов и кода вместе, вам может потребоваться использование текстовых форматов для документации. Существует несколько инструментов, совершающих правильное отслеживание в репозитории бинарных файлов. В случае с текстовыми форматами вы можете просто создавать диффы между различными версиями (коммитами) файлов и смотреть, в чём различия.

Для изображений пуристы часто используют текстовый формат SVG (Scalable Vector Graphics). Но вы можете использовать стандартные форматы, такие как PNG или JPG, и просто принять, что вам потребуется вручную сравнивать различные версии изображений в случае необходимости.

Доклад Сары на саммите STC 2015 был посвящён тому, как git позволяет вам заниматься археологией своего проекта. Идя по следам коммитов, вы можете увидеть, какую работу сделали разработчики. Если кто-то из разработчиков забыл вам рассказать о небольшой, но критической детали, вы можете найти её в этих отчётах. Если разработчики используют многословные комментарии к коммитам (что в некоторых случаях является обязательным требованием), ваши шансы разобраться во всём возрастают ещё больше. По моему опыту, учитывая комбинацию читабельных комментариев в системе контроля версий, применяемых в рецензировании кода, а также последующее использование JIRA, практически невозможно не заметить изменения в программном обеспечении, если технический писатель уделяет этому хоть какое-то внимание.

Психология «коммитов»

Как и писатели, многие из нас хотят выполнять работу идеально перед тем, как кто-либо увидит результат. Нам трудно показывать грубую, незаконченную работу. Тем не менее, если вы хотите закоммитить свою работу и следовать обычному рабочему эджайл-процессу, вы не должны быть идеальными. Культура вашего рабочего места и особый тип проекта (например, работа управленца или RFP) влияет на производственный процесс, но опыт показывает, что команде важнее увидеть что-то неидеальное раньше, чем ничего не видеть неделями вообще, и затем им придётся сказать, что вы были всё это время не правы. Когда вы начинаете с чего-то неидеального, процесс обратной связи позволяет вам делать работу лучше. Имейте в виду, что вам нужно найти способ чувствовать себя комфортно по отношению к окончательному состоянию документа, перед тем, как он будет представлен для широкой аудитории, даже если он менее идеален, чем бы вам хотелось. На конференции Write the Docs в 2015 году писатель из Atlassian сказал прямо, что при их непрекращающемся процессе поставки им необходимо принимать документы, которые иногда не полностью обновлены. Будьте честны и открыты для вашей команды и для ваших начальников в отношении того, что можете сделать и что они ожидают.

Git против SVN (Subversion)

И SVN (Subversion), и git являются системами контроля версий, двумя способами создания репозиториев, в которых вы можете коммитить изменения и тщательно отслеживать всё, что вообще происходит с вашей кодовой базой. Но эти две программы имеют некоторые различия в реализации и несколько разную философию. Вы можете начать с git, потому что Github доступен бесплатно и лёгок в изучении.

Мне более привычен SVN, который я использую с 2008 года для работ с закрытым программным обеспечением. Нам требуется всё дерево SVN, чтобы продукт стал готовым к релизу, а каждый разработчик работает с веткой, часто несколько разработчиков (писателей или кодеров) работают с одной и той же веткой. По моему опыту, если технические писатели и программисты работают вместе таким образом, все они закончат свою работу одновременно (разрабатывать и документировать), что способствует развитию их культуры. SVN даёт пользователям возможность ограничивать по функциональности отдельные файлы или целые ветки, если важно предотвратить внесение мгновенных изменений. SVN хороша для создания централизованной культуры, и для малых, и для больших команд. SVN также имеет репутацию более простой для начального изучения системы, с пронумерованными коммитами, которые легче отслеживать по отчётам.

Одна git имеет множество преимуществ сама по себе. Она продвигает децентрализованное видение мира, без главного репозитория с привилегированным положением. Это видение хорошо работает на многих открытых проектах. С помощью git вы можете регулярно коммитить в свою ветку, даже если у вас нет доступа к сети. При использовании SVN каждый коммит требует доступа к сети, что может препятствовать осуществлению коммитов с необходимой частотой. Для большой децентрализованной команды проблемы с сетью, которые могут мешать разработчикам подключаться к центральному репозиторию, более вероятны.

Оболочка Git Bash — один из способов взаимодействия с git, но также доступны другие оболочки, включая оболочки с графическим интерфейсом.

JIRA, инструмент от Atlassian, который стал обязательным во многих компаний для использования в качестве багтрекера, трекера отслеживания функций и возможности планировать спринты, может работать и с git, и с SVN. Рецензирование кода, управляющееся открытым способом — важная часть процесса разработки (и если документы сохраняются в виде кода, рецензирование кода также работает и для документов).

Для рецензирования кода я использую Code Collaborator, который хорошо работает с SVN, и моё исследование показывает, что CC может также хорошо работать и с git. Также доступно множество других инструментов для рецензирования кода.

Я игнорирую другие программы контроля версий, такие как perforce и Mercurial. Однако к ним применимы те же основные принципы. В целом, если вы хотите начать прямо сейчас работать в системе контроля версий для собственного проекта, используйте git. Если вы работаете в компании, которая использует SVN или другую систему контроля версий, и она правильно внедрена, у вас всё будет хорошо. Просто убедитесь, что совершаете коммиты согласно правилам вашей команды, и делаете это достаточно часто. Вы не можете отслеживать изменения, если не коммитите эти изменения, и можете потерять свою работу, если не совершаете коммиты регулярно. Как часто? У вашей команды могут быть свои правила, но, по моему мнению, не стоит это делать реже, чем раз в день, если вы вообще работали с этим файлом в этот день.

SVN и git имеют команды, которые пугают даже опытных пользователей. Для меня в SVN это команда switch, потому что с помощью неё очень легко «запороть» ветку. В git, насколько я читал, опасна команда rebase. Но вы должны очень постараться, чтобы совершить настолько неисправимое изменение, что оно будет хуже полного отсутствия коммитов.

Преимущество текстовых инструментов для рецензирования кода

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

Бинарные форматы обычно проприетарные. Например, если использовать неструктурированный FrameMaker для создания .fm-файлов, то только те сотрудники, у которых есть FrameMaker, смогут увидеть исходные файлы. Вы можете раздать свои PDF-ки экспертам по предмету, и возможно, другие инструменты для рецензирования, но я точно убедился, что использование инструментов рецензирования кода несоизмеримо лучше.

Github поддерживает собственную версию Markdown, очень простую систему текстового форматирования, которая хорошо работает для технических писателей, интегрирующих свои документы с кодом. Разработчики любят Markdown, потому что его формат легко читать, с его помощью легко писать, и составлять описания можно в любом техническом редакторе, будь то emacs, Oxygen или Блокнот.

Github также позволяет без проблем совместно работать группе, внутри которой используются разные операционные системы. У одного разработчика может быть Mac, другой может использовать Linux, а ещё один — Windows, но это не имеет значения для git и Github. По моему опыту, могут быть некоторые сложности в совмещении SVN в Linux и SVN в Windows вследствие тонких программных различий.

Принимая во внимание, что DITA использует XML-файлы, являющиеся текстом, DITA может хорошо работать в производственном процессе, в котором интегрированы документы в код. Хотя человек, не знакомый с DITA, не сможет редактировать файлы, что делает DITA несколько менее открытым, чем «человекочитаемые» форматы, такие как Markdown или restructuredText.

Ваш сайт Github в качестве портфолио

Я часто читаю о HR-менеджерах, которые говорят, что хотят увидеть работы разработчика программного обеспечения на Github. Конечно, многие из нас работают в компаниях, у которых нет свободного программного обеспечения, так что мы определённо не можем выложить эту работу в Github на всеобщее обозрение. Тем не менее, Github — отличное место для хранения проектов, которые вы можете сделать общедоступными. Если вы сделали работу самостоятельно, ваши коммиты расскажут историю для любого, кто исследует отчёты. В отличие от явного плагиата, вы не можете подделать работу, которую сделали в репозитории Github (или SVN).

Github для совместной работы

Многие писатели считают Google Docs лучшим решением для совместного писательства. Я его использовал, когда Том Джонсон (Tom Johnson) редактировал в сентябре 2014 года публикацию для STC Intercom о документировании API, я тогда был соавтором этой статьи.

Но Gitub также хороший способ взаимодействия. Хотя вы и не можете видеть, как все остальные набирают в реальном времени, вы можете легко прокрутить вперёд и назад и увидеть, кто какие внёс изменения. Если вы и ваш соавтор делаете что-то, что конфликтует друг с другом, Github поможет вам разрешить этот конфликт.

Что доступно на Github?

Многие открытые проекты перемещены на Github. Просто совершите поиск на тему, которая вас интересует, например, «музыка», и вы обнаружите по крайней мере один проект, который к этому относится. Когда вы посещаете веб-сайт открытого проекта, то скорее всего увидите ссылку на его Github-репозиторий.

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

Источник: Git, Github, Source Control, and You

Тэги: инструменты, командная работа, организация работы, форматы