48 views
# Да кто такой этот ваш github? или Базовые концепции > Git gets easier once you understand branches are homeomorphic endofunctors > mapping submanifolds of a Hilbert space > > (c) [@agnoster](https://twitter.com/agnoster/status/44636629423497217) > Git становится проще, когда понимаешь, что ветки являются гомеоморфными > эндофункторами, отображающими подмногообразия гильбертова пространства Программисты часто используют **системы контроля версий** - в них хранятся тексты, которые меняются и различные версии которых бывает нужно сравнивать. Системы контроля версий могут использоваться и не только программистами. Далее речь будет идти об одной системе контроля версий, которая называется **git**. Все тексты хранятся в виде текстовых файлов (т.е. не бинарных; часто изменяемые бинарные файлы, такие как docx, картинки и т.п. лучше не хранить в репозтории). Это сделано для того, чтобы эффективно отслеживать изменения: в каких строках какие слова изменились. Если файл бинарный, то даже при изменении одного слова может меняться слишком большая часть файла. ![скрин диффа](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/diff.png) Каждое изменение в набор файлов называется **коммитом**. Вместе с самим изменением хранится, кто и когда его внёс и краткое описание изменения. Как правило, коммит содержит изменения в набор файлов, объединённые общим смыслом. Также в коммите хранится, какое изменение было предыдущим. Адрес коммита вычисляется на основе его содержимого, поэтому можно увидеть, что не было никакой подмены. ![скрин коммита](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/commit-desc.png) Репозиторий хранится в виде набора коммитов. Если известен последний коммит, то можно восстановить цепочку от него до начального. При этом получается, что в репозитории может иметь несколько последних коммитов - которые в какой-то момент сходятся к одной точке. Каждый такой набор называется **веткой** - потому что весь репозиторий начинает напоминать дерево. ![картинка - дерево в репозитории](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/repo-tree.png) От обычных деревьев репозиторий отличает возможность **слияния** (merge) веток. При этом в одну из веток вставляется коммит специального вида. Создание и слияние веток можно использовать для одновременной работы над разными версиями документов и для выделения истории работы над связанным набором документов. Хотя репозитории git могут храниться у любого участника на его компьютере, обычно удобнее иметь сервер, на котором репозиторий доступен в любой момент. Одним из популярных сервисов, предоставляющих хранение репозиториев, является **github**. Кроме собственно доступа к репозиториям, github предоставляет и другие полезные функции. Например, его интерфейс позволяет удобно просматривать и вести обсуждение при слиянии веток - при помощи **пулл-реквестов** (Pull Request); или создавать и обсуждать **задачи**. # Как выполнить типичные действия? Чтобы работать с репозиторием документов МАИИ, нужно зайти на https://github.com/maii-chgk/documents. Для просмотра регистрации не требуется; регистрация необходима для внесения изменений и их обсуждения. ## Посмотреть список действующих документов МАИИ Список действующих документов со ссылками поддерживается в README. Github показывает этот файл в красивом виде, если открыть репозиторий https://github.com/maii-chgk/documents. ![скрин репозитория](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/maii-repo.png) ## Посмотреть действующий текст документа По ссылкам в README, либо напрямую в списке папок и файлов можно открыть отдельные документы. Так, например, выглядит Устав МАИИ на русском языке: https://github.com/maii-chgk/documents/blob/main/statute.ru.md ![скрин документа](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/repo-doc.png) ## Посмотреть изменения в документе При просмотре любого документа можно нажать на ссылку "History" (история). ![скрин с пометкой](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/repo-doc-history.png) По нему открывается список коммитов, которые изменяли этот документ. По нажатию на любой из них можно увидеть изменения, внесённые этим коммитом (в текстовом виде). ![скрин с историей](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/history.png) Нажав у соответствующего файла кнопку с многоточием и выбрав "View file", можно увидеть файл в той редакции, которая была после данного коммита ![скрин с пометкой](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/history-show-file.png) На самом деле, можно сравнить любую версию репозитория с любой другой. Для этого достаточно знать адреса коммитов этих версий и вставить их в ссылку вместо `ADDR1` и `ADDR2`: https://github.com/maii-chgk/documents/compare/ADDR1...ADDR2 Адреса коммитов можно увидеть в истории изменений и скопировать по нажатию кнопки с планшетом ![скрин с пометками](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/repo-history.png) ## Посмотреть предлагаемые документы Предлагаемые документы можно посмотреть точно так же, как и действующие, но в соответствующей ветке. Выбор ветки производится в выпадающем списке ![скрин с ветками](https://gist.github.com/gltronred/bf68b7b99c2a4778d4c0f761be7872e7/raw/c3c2ab4578753078befe7e3637ef62a3eae5fc43/repo-branches.png) ## Оставить лайки ## Обсуждать изменения ## Предложить изменения # Как МАИИ хранит в репозитории тексты документов Для документов практически не требуется форматирование, поэтому используется формат markdown. Он позволяет выделять заголовки, делать списки и ссылки. Github отображает markdown-документы в "красивом" виде, со всеми этими выделениями. Также markdown легко преобразовать в docx, html, pdf и другие форматы. ## Заголовки Заголовки разных уровней выделяются нужным количеством символов `#` в начале строки: ``` # Заголовок 1 ## Заголовок 2 ### Заголовок 3 ``` ## Текст и абзацы, выделения в тексте Текст пишется обычным текстом. Абзацы разделяются пустой строкой. Одинарные разрывы строк не важны и могут использоваться для удобства написания. Есть **полужирный**, *курсив*, _подчеркивание_ и ~~зачеркивание~~. ``` Текст пишется обычным текстом. Абзацы разделяются пустой строкой. Одинарные разрывы строк не важны и могут использоваться для удобства написания. Есть **полужирный**, *курсив*, _подчеркивание_ и ~~зачеркивание~~. ``` ## Списки Элементы ненумерованных списков начинаются с символа `-`, `*` или `+`. На одном уровне должны быть одинаковые символы. Выбор самих символов - произвольный и влияет только на читаемость кода. Элементы нумерованных - с числа, точки и пробела. Число может быть одним и тем же, в "красивом" виде они будут идти по порядку. Вложенные списки выделяются отступом - он должен быть одним и тем же у одноуровневых элементов списка. Более глубокие элементы должны иметь больший отступ. ``` - ненумерованный список - ещё элемент + вложенный список + и ещё того же уровня - и ещё 1. Можно 2. вложить 3. нумерованный 4. список 1. А вот нумерованный 2. Второй элемент 3. Третий 1. Числа не важны - этот будет показан четвертым ``` ## Ссылки и якоря Ссылки используют следующий формат: `[текст ссылки](адрес ссылки)`. Адрес ссылки может быть: - произвольным URL и начинаться с `http://` или `https://` (например, `[Google](https://google.ru)`). Просто URL тоже отображаются в виде ссылок, у которых текст - это адрес; - ссылкой на файл в том же репозитории, тогда в качестве адреса нужно указать относительный адрес файла, например, `[Устав](statute.ru.md)` или `[Шаблон регламента](wg/_template.ru.md)`; - ссылкой на конкретное место в текущем документе, тогда в качестве адреса нужно указать имя якоря с `#` в начале, например, `[п. 1.2.3](#ref1_2_3)`; - ссылкой на конкретное место в другом документе, тогда в качестве адреса нужно указать относительный адрес файла и имя якоря, например, `[п. 1.2.3 Устава](statute.ru.md#ref1_2_3)`. Якоря - места, на которые в документе можно ссылаться. Если якорь указан неверно, ссылка будет указывать на весь документ в целом. Любой заголовок является якорем, а его именем является текст заголовка, в котором пробелы заменены дефисами и все буквы - строчными (например, `#как-маии-хранит-в-репозитории-тексты-документов`). В любое место документа можно поставить якорь вручную, для этого нужна конструкция `<a name="ANCHOR"></a>`, где ANCHOR - имя якоря. ## Метаинформация Документ также может хранить метаинформацию (например, заголовок документа) в виде пар ключ-значение. Для этого в начале документа можно указать следующий блок: ``` --- key1: var1 title: value of title other-key: other-value ``` Здесь ключами являются `key1`, `title` и `other-key`, а значения для этих ключей записаны после двоеточия в соответствующих строках # Внутренние соглашения (идёт обсуждение) ## Названия файлов Файлы называются на английском так, чтобы было понятно их содержимое: - `statute` - устав; - `membership` - положение о членстве. Если в названии несколько слов, вместо пробелов они разделяются дефисами: - `executive-committee` - положение об исполкоме; - `working-groups` - положение о рабочих группах. Для всех документов используются постфиксы ru и de в зависимости от языка документа: - `statute.ru.md` - устав на русском; - `statute.de.md` - устав на немецком. Поскольку большинство документов не требуют перевода, для них есть только версия с постфиксом `ru`. Он остаётся, поскольку контрагенты организации могут потребовать перевод на немецкий. ## Метаинформация (обсуждение) Сейчас используется только строка `title` для названия документа. ## Названия ссылок (обсуждение) Для ссылок на конкретное место в документе в репозитории необходимо дать название ссылке (адрес, который будет в тэге `a name`). Сейчас все ссылки привязаны к номеру (например, `ref3_4_1` для пункта 3.4.1). Лучше, если в этих ссылках будет указан смысл пункта (например, `decision-motivation`). Тогда при изменении нумерации не будет удивления от ссылок. Допустим в п.3 добавили ещё один подпункт до 3.4. При текущей системе ссылка станет выглядеть так: `В соответствии с п. [3.5.1 Устава](statute.ru.md#ref3_4_1) предоставлять по запросу членов МАИИ информацию о мотивировке и порядке принятия своих решений.` При ссылках со смыслом пункта так: `В соответствии с п. [3.5.1 Устава](statute.ru.md#decision-motivation) предоставлять по запросу членов МАИИ информацию о мотивировке и порядке принятия своих решений.` ## Папки (обсуждение) На данный момент создана папка `wg` для регламентов о рабочих группах. В ней находится шаблон регламента `wg/_template.md` ## Ветки репозитория (обсуждение) Сейчас для каждого ОС, принимающего изменения в документах создаётся ветка вида `general-meeting-YYYY-MM-DD`, в которой вносятся коммиты, по одному на каждое голосование. В дальнейшем можно перейти на ветки вида `general-meeting-YYYY-MM-DD/NN-NAME`, по одной ветке на каждое голосование. Это может быть удобным, если публиковать документы до голосования в репозитории, сравнивать и обсуждать их там же, а по результатам голосований либо сливать в ветку `main`, либо оставлять для доработки. # Дополнительная литература [1] https://brennan.io/2015/08/07/github-noncoders/ [2] https://readwrite.com/2013/11/08/seven-ways-to-use-github-that-arent-coding/ [3] https://github.github.com/gfm/