exam/CONTRIBUTING.md

---
tags:
  - служебное
---
# Соглашения о вкладе

## Стиль билетов

> [!attention]+ Основное требование к билету
>**НЕ ПРОСТО ПЕРЕПИСЫВАЙТЕ МЕТОДИЧКУ СЛОВО В СЛОВО**: старайтесь ужать материал и сделать его как можно понятнее

*Иначе смысла в написании билетов нет ни для вас, ни для человека, который может их почитать. Разбиение методички на билеты - не самая важная часть нашей деятельности*

При написании билетов я предполагаю, что пользователь сидит в режиме чтения
### Объем билетов

Довольно очевидно, что билеты должны быть максимально короткими, чтобы человек не учил то, что может не учить, но при этом они не должны быть невнятными. Старайтесь выдерживать золотую середину между читаемостью и объемом

Периодически в билете требуется пояснить моменты, которые вообще говоря не надо запоминать и они не связаны с ответом, но они помогают пониманию билета. В таком случае я обычно пишу что-то вроде:

> [!comment]- Примечание билетера о ...
> Какое-то пояснение, которое я считаю важным дать, но которое не важно во время ответа

Оформляется оно при помощи коллаутов примерно так:

```md
> [!comment]- Примечание билетёра о ...
> lorem ipsum dolor sit amet
```

Также считаю допустимым использование примечаний^[Это примечание отобразится в конце страницы и не будет так сильно отвлекать от билета]. Они автоматически складываются в конце страницы и при наведении на них всплывает подсказка, что тоже довольно удобно для пояснений

## Шаблоны

У нас есть 2 шаблона. Фактически стандартизируют они только подложку заметки:

- Билет - содержит поля под:
	- теги
	- [[#Закон каламбура|каламбур]]
	- автора (указываете свой ник или как вам удобно представиться)
	- ревизию (это поле для ElectronixTM, потому что его попросили верифицировать все написанное. Он укажет туда информацию о ревизии)
- Заметка - просто любая заметка на ваш вкус, которая может содержать дополнительную информацию, которая не идет в билеты. Для первых 4 билетов в таких написаны конспекты некоторых разделов билетов

## Дирректории

В проекте у нас есть главная папка: "Билеты". Пояснять, думаю, не надо, а также папка: "Дополнительно". В папку дополнительно идет все, что только пожелаете. В этой папке есть еще и digital garden - можете погуглить "второй мозг", "zettelkasten" и "commonplace". У меня была идея с этим что-то придумать, но как бы не вышло, но может вы захотите хранить такие вот атомизированные заметки в каком-то месте

## Именование файлов

Все названия файлов подчиняются следующему шаблону: `xx - название`. Тут все стандартно как с физикой

## Ветки

Так как я больше не один, надо бы по веточкам работать. Именование веток довольно произвольное. Обойдемся стандартным набором, только модифицируем его:

- `feat` - под всё новое
	- `feat/tickets/xx` - Написание нового билета должно проходить именно в таких ветках
- `fix` - какие-то исправления в уже написанном материале
- `other` - все, что не подвязывается к первым двум

Пул реквесты можете делать, но тогда сразу назначайте человека, который будет вас проверять, а потом желательно сразу же ему писать в личку (благо все свои). Если что, можете сразу мерджить изменения в мастер, тут расчет на вашу адекватность

## Коммиты

Тут все по стандарту conventional commits. Все сообщения к коммитам пишутся на русском, с маркерами:

1. `feat` - сделал что-то новое
2. `fix` - починил что-то старое
3. `chore` - убирание тегов, изменение названий, в общем всякая мелочь

### Примеры

- `feat: написал конспект 3 главы 3.2 раздела`
- `chore: удалил тег "в процессе"`

*Просьба просто в том, чтобы человек не открывая коммит мог получить представление о том, что вы там сделали, так что не надо чего-то вроде: fix, fix, fix, fix*

## Разрешенные плагины для Obsidian

В [[README]] я уже говорил, что все билеты пишутся под Obsidian, а поскольку он поддерживает разные плагины, есть соблазн поставить парочку. В связи с этим регулировка такая:

- Разрешены любые плагины до тех пор, пока все, что вами написано, нормально рендерится в ванильном обсидиане без единого плагина. 

Может закон и не точный, но и мы не на уроке права, поэтому поясню мысль и буду надеяться на благоразумие:

Мы уже предъявляем определенные требования к пользователю - он должен открывать этот проект непременно в обсидиане. Так давайте же уважим его и не будем заставлять еще и скачивать плагины

## Использование тегов

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

- Обязательно проверьте, какие теги уже существуют
- Есть небольшой набор служебных тегов, которые призваны помогать искать недоделки и недоработки

### Стиль тегов

Все теги должны быть на **русском** языке и начинаться со *строчной* буквы. Слова отделяются нижними подчеркиваниями. Например (примеры обернуты чтобы они не отображались при поиске по тегам):

- `#математика`
- `#русский_язык`

Также Obsidian из коробки поддерживает вложенные теги: `#это/пример/вложенного/тега`

ограничения те же, что и на все остальные теги
### Служебные теги

Все служебные заметки начинаются со специальной комбинации `#служебное/`

- #служебное/доработать - заметка в целом закончена, но нужно внести некоторые доработки
- #служебное/в_процессе - заметка еще пишется, а это промежуточный результат работы
- #служебное/устарело - Препод поменял билеты, поэтому то, что было написано, не совсем актуально. Все, что не актуально, и еще не пересмотрено помечается деприкейтится этой меткой

Эти теги служат только для передачи служебной информации о состоянии заметки

## Закон каламбура

Каждый билет должен сопровождаться каламбуром. Эти каламбуры вставляются в подложку заметки. Тема не важна, но это должен быть обязательно **каламбур**