# Да кто такой этот ваш 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/