# Да кто такой этот ваш 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, картинки и т.п. лучше не хранить в репозтории).
Это сделано для того, чтобы эффективно отслеживать изменения: в каких строках
какие слова изменились. Если файл бинарный, то даже при изменении одного слова
может меняться слишком большая часть файла.
Каждое изменение в набор файлов называется **коммитом**. Вместе с самим
изменением хранится, кто и когда его внёс и краткое описание изменения. Как
правило, коммит содержит изменения в набор файлов, объединённые общим смыслом.
Также в коммите хранится, какое изменение было предыдущим. Адрес коммита
вычисляется на основе его содержимого, поэтому можно увидеть, что не было
никакой подмены.
Репозиторий хранится в виде набора коммитов. Если известен последний коммит, то
можно восстановить цепочку от него до начального. При этом получается, что в
репозитории может иметь несколько последних коммитов - которые в какой-то момент
сходятся к одной точке. Каждый такой набор называется **веткой** - потому что
весь репозиторий начинает напоминать дерево.
От обычных деревьев репозиторий отличает возможность **слияния** (merge) веток.
При этом в одну из веток вставляется коммит специального вида. Создание и
слияние веток можно использовать для одновременной работы над разными версиями
документов и для выделения истории работы над связанным набором документов.
Хотя репозитории git могут храниться у любого участника на его компьютере,
обычно удобнее иметь сервер, на котором репозиторий доступен в любой момент.
Одним из популярных сервисов, предоставляющих хранение репозиториев, является
**github**.
Кроме собственно доступа к репозиториям, github предоставляет и другие полезные
функции. Например, его интерфейс позволяет удобно просматривать и вести
обсуждение при слиянии веток - при помощи **пулл-реквестов** (Pull Request); или
создавать и обсуждать **задачи**.
# Как выполнить типичные действия?
Чтобы работать с репозиторием документов МАИИ, нужно зайти на
https://github.com/maii-chgk/documents. Для просмотра регистрации не требуется;
регистрация необходима для внесения изменений и их обсуждения.
## Посмотреть список действующих документов МАИИ
Список действующих документов со ссылками поддерживается в README. Github
показывает этот файл в красивом виде, если открыть репозиторий
https://github.com/maii-chgk/documents.
## Посмотреть действующий текст документа
По ссылкам в README, либо напрямую в списке папок и файлов можно открыть
отдельные документы. Так, например, выглядит Устав МАИИ на русском языке:
https://github.com/maii-chgk/documents/blob/main/statute.ru.md
## Посмотреть изменения в документе
При просмотре любого документа можно нажать на ссылку "History" (история).
По нему открывается список коммитов, которые изменяли этот документ. По нажатию
на любой из них можно увидеть изменения, внесённые этим коммитом (в текстовом
виде).
Нажав у соответствующего файла кнопку с многоточием и выбрав "View file", можно
увидеть файл в той редакции, которая была после данного коммита
На самом деле, можно сравнить любую версию репозитория с любой другой. Для этого
достаточно знать адреса коммитов этих версий и вставить их в ссылку вместо
`ADDR1` и `ADDR2`: https://github.com/maii-chgk/documents/compare/ADDR1...ADDR2
Адреса коммитов можно увидеть в истории изменений и скопировать по нажатию
кнопки с планшетом
## Посмотреть предлагаемые документы
Предлагаемые документы можно посмотреть точно так же, как и действующие, но в
соответствующей ветке. Выбор ветки производится в выпадающем списке
## Оставить лайки
## Обсуждать изменения
## Предложить изменения
# Как МАИИ хранит в репозитории тексты документов
Для документов практически не требуется форматирование, поэтому используется
формат 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/