Настройка документации

documentation/ru/docs/architecture/concept.md

@@ -2,7 +2,8 @@
 
 Поддерживается два режима работы: периодические запуски на ПК и запуск на сервере в режиме 24/7.
 
-## Схема БД
+## Схема БД { id="schema-database" }
+
 Приложение имеет БД, которая используется для сохранения состояния отслеживаемых сущностей GitLab.
 
 <figure markdown>

documentation/ru/docs/features/notify.md

@@ -1,38 +1,108 @@
 # :bell: Уведомления
 Основное предназначение бота - это уведомления от GitLab. Вы будете получать только те уведомления, которые касаются вас непосредственно.
 
-## Новый репозиторий
+## Новый репозиторий { id="new-repository" }
+Если во время первичной настройки вы указали, что хотите получать уведомления о новых репозиториях, то при появлении нового репозитория получите соответствующее уведомление:
+<figure markdown>
+![notify about new merge request](img/notify-new-project.png){ loading=lazy width="500" }
+</figure>
+
+Уведомление содержит:
+
+- Project name — название репозитория.
+- Project description — описание репозитория. Опционально, может быть пусто.
+- Struchkov Mark — имя создателя репозитория в GitLab
+
+Доступно три быстрых действия:
+
+- :link: — ссылка на новый репозиторий в GitLab.
+- :bell: — поставить на отслеживание. Вы начнете получать уведомления о событиях в MR, тредах и сборках.
+- :no_bell: — не получать уведомления. Используется по умолчанию, по факту просто удаляет сообщение уведомления.
+
+!!! warning ""
+
+    Пока вы явно не нажмете :bell:, вы не будете получать никаких уведомлений. Более того, приложение даже не будет запрашивать MR и прочие сущности репозитория, не будет сохранять их в БД.
+
+## Новый MR { id="new-mr" }
+Это уведомление приходит, когда вас назначают ответственным и/или ревьювером.
 
-## Новый MR
-Когда кто-то создает MR и назначает вас ответственным и/или ревьювером, то вам приходит уведомление. Из этого уведомления можно узнать название, короткое описание, теги, из какой ветки в какую открыт MR, кто его автор и кто ответственный.
 <figure markdown>
 ![notify about new merge request](img/notify-new-mr.png){ loading=lazy width="500" }
 </figure>
 
-## Конфликт в MR
+Уведомление содержит:
+
+- Название MR.
+- Описание MR. Опционально.
+- Labels. Метки репозитория.
+- Имя проекта.
+- Ветки откуда куда мержим.
+- Автор MR.
+- Ответственный/Ревьюверы MR. Заполнение зависит от вашей позиции в этом MR. Если вы ответственный, то вам покажут ревьюверов. Если вы ревьювер, то ответственного.
+
+Доступные быстрые действия:
+
+- :eyes: — прочитано. Удаляет сообщение.
+- :link: — ссылка на MR.
+- :no_bell: — не получать уведомления по MR.
+
+!!! warning ""
+
+    Учтите, что отключение уведомлений отключает только уведомления об изменениях в MR. Например, обновление статуса MR. Но уведомления по пайплайнам проекта, по тредам MR продолжат приходить.
+
+## Конфликт в MR { id="conflict-mr" }
 Если в вашем MR возник конфликт, то вы будете своевременно оповещены. В этом уведомлении указывается название MR, проект и ветка.
 
 <figure markdown>
 ![notify about conflict in merge request](img/notify-conflict-mr.png){ loading=lazy width="500" }
 </figure>
 
-## Обновление MR
+Доступные быстрые действия:
-Когда кто-то делает коммиты в MR, в котором вы ответственный или ревьювер, вам сразу же приходит уведомление. Вы также сразу можете увидеть сколько задач еще не решено, и сколько созданных вами задач не было решено.
+
+- :eyes: — прочитано. Удаляет сообщение.
+- :link: — ссылка на MR.
+- :no_bell: — не получать уведомления по этому MR.
+
+## Обновление MR { id="update-mr" }
+Если в MR, в котором вы являетесь ответственным/ревьювером, добавляются коммиты, вы получаете уведомление.
 
 <figure markdown>
 ![notify about update in merge request](img/notify-update-mr.png){ loading=lazy width="500" }
 </figure>
 
+Уведомление содержит:
+
+- Название MR.
+- Отношение количества закрытых тредов к общему количеству созданных тредов.
+- Отношение количества закрытых вами созданных тредов к общему количеству созданных вами тредов.
+- Название репозитория.
+- Имя создателя MR.
+
+Доступные быстрые действия:
+
+- :eyes: — прочитано. Удаляет сообщение.
+- :link: — ссылка на MR.
+- :no_bell: — не получать уведомления по этому MR.
+
 ## Изменение статуса MR
 Когда статус вашего MR меняется, вы получаете уведомление.
 
+<figure markdown>
+![notify about update status in merge request](img/notify-update-status-mr.png){ loading=lazy width="500" }
+</figure>
+
+Доступные быстрые действия:
+
+- :eyes: — прочитано. Удаляет сообщение.
+- :link: — ссылка на MR.
+
 ## Новый тред в MR
-В GitLab можно создавать не просто комментарии, а обсуждения (Discussions). Если кто-то создаст такое обсуждение в вашем MR, то вы сразу об этом узнаете.
+В GitLab можно создавать не просто комментарии, а треды. Если кто-то создаст такое обсуждение в вашем MR, то вы сразу об этом узнаете.
 
 ## Упоминание в треде
 Допустим, кто-то упомянул вас в MR, нужен ваш совет. Автор этого MR не вы, ответственным назначали тоже не вас. Даже в этом случае вам придет уведомление, так вы не пропустите сообщения с вашим упоминанием.
 
-## Ответ в дискусии
+## Ответ в треде
 Важно оставаться в теме обсуждения, поэтому при появлении новых ответов в дискуссия, в которых вы участвовали, вы получите уведомление.
 
 Оно будет содержать начальное сообщение обсуждения, ваше последнее сообщение в нем, а также два последних комментария. Таким образом вы будете понимать о чем идет речь.

documentation/ru/docs/privacy.md

@@ -1,25 +0,0 @@
-# :ninja: Конфиденциальность
-
-
-
-Мое решение сфокусировано на приватности и прозрачности. Код и используемые зависимости полностью открыты и доступны для изучения и самостоятельной сборки.
-
-Для работы бота токен доступа устанавливается в переменные среды и никуда не передается, кроме запросов в GitLab.
-
-Некоторые уведомления могут содержать чуствительную информацию. Например, уведомления о новых сообщениях в тредах. Возможно вы не захотите раскрывать столько информации о ваших репозиториях Телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений.
-
-Возьмем для примера уведомление о новом сообщении в треде. При минимальном уровне конфиденциальности вы получите уведомление с текстом коментария и сможете сразу ответить на него в телеграм, а при максимальном уровне конфиденциальности будет сообщаться только о факте нового комментария, без содержания. Все это настраивается при первом запуске.
-
-## Несанкционированный доступ
-==Все боты в Telegram являются публичными.== Это значит, что ваш бот может быть найден через поиск в Telegram. Поэтому ==не рекомендуется давать название боту, которое может раскрыть его предназначение.==
-
-Даже если кто-то случайно напишет вашему боту ничего не случится. ==В боте встроена проверка прав доступа.== Вот как она работает:
-
-1. При запуске вы указываете ваш идентификатор в Telegram. В отличие от логина, идентификатор уникален для каждого пользователя и нет возможности его подменить.
-2. Когда бот получает сообщение, он проверяет идентификатор отправителя
-3. Если идентификатор отправителя не совпадает с указанным при запуске, бот не обрабатывает команду
-4. Вы получаете уведомление о том, что такой-то пользователь пытался написать в ваш бот. Вам доступен логин этого пользователя в Telegram, а также текст его сообщения. Это поможет понять является ли попытка доступа злонамеренной и принять меры.
-
-> Уведомления от GitLab всегда отправляются только указанному в конфигурации пользователю.
-
-Демонстрация работы системы защиты:

documentation/ru/docs/privacy/index.md

@@ -0,0 +1,40 @@
+# :ninja: Конфиденциальность
+
+Я разработчик, и это приложение должно помогать мне работать, оптимизируя мое время взаимодействия с GitLab. В какой-то момент я решил подлиться своими наработками со всеми желающими. Часто в GitLab содержится множество конфиденциальной информации, которую не хотелось бы раскрывать. Эта страница пытается ответить на все вопросы, которые могут вас смущать.
+
+!!! tip "Доверие"
+
+    Вы не должны верить мне на слово. Вы можете [самостоятельно изучить код, он открыт и не сложен.](https://github.com/uPagge/gitlab-notification) После проверки можно самостоятельно собрать jar и упаковать его в Docker. Либо запускать код прямо из Idea.
+
+## Защита токена GitLab
+Для работы ассистента необходим персональный токен GitLab. Он указывается в переменные среды и нигде дополнительно не дублируется. Таким образом токен не попадает в Telegram и хранится только у вас на компьютере и в контейнере приложения.
+
+Токен используется только при обращении к указанному GitLab, и только для выполнения описанных в документации возможностей. Никакой скрытой работы не выполняется, по возможности обо всех взаимодействиях с GitLab дополнительно сообщается во время настройки.
+
+## Уровни конфиденциальности
+
+Некоторые уведомления могут содержать множество чувствительной информации. Например, уведомления о новых сообщениях в тредах. Возможно вы не захотите раскрывать столько информации о вашей разработке телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений.
+
+Возьмем для примера уведомление о новом сообщении в треде. При минимальном уровне конфиденциальности вы получите уведомление с текстом комментария и сможете сразу ответить на него в телеграм, а при максимальном уровне конфиденциальности будет сообщаться только о факте нового комментария, без содержания. Все это настраивается при первом запуске.
+
+## Сохранение в БД
+Для работы ассистента ему нужно сохранять предыдущее состояние GitLab сущностей. Для этого используется БД. Приложение старается не хранить в БД больше данных, чем необходимо. Как только необходимость в данных теряется, например MR мержится, данные из БД удаляются.
+
+Прочитать подробнее можно в разделе: [Работа с базой данных](../architecture/concept.md#schema-database)
+
+## Несанкционированный доступ
+==Все боты в Telegram являются публичными.== Это значит, что ваш бот может быть найден через поиск в Telegram. Поэтому ==не рекомендуется давать название боту, которое может раскрыть его предназначение.==
+
+Даже если кто-то случайно напишет вашему боту ничего не случится. ==В боте встроена проверка прав доступа.== Вот как она работает:
+
+1. При запуске вы указываете ваш идентификатор в Telegram. В отличие от логина, идентификатор уникален для каждого пользователя и нет возможности его подменить.
+2. Когда бот получает сообщение, он проверяет идентификатор отправителя
+3. Если идентификатор отправителя не совпадает с указанным при запуске, бот не обрабатывает команду
+4. Вы получаете уведомление о том, что такой-то пользователь пытался написать в ваш бот. Вам доступен логин этого пользователя в Telegram, а также текст его сообщения. Это поможет понять является ли попытка доступа злонамеренной и принять меры.
+
+<figure markdown>
+  ![unauth-access.png](unauth-access.png){ loading=lazy width="500" }
+  <figcaption>уведомление о несанкционированном доступе</figcaption>
+</figure>
+
+Для злоумышленника все выглядит так, как будто бот не работает. Никаких ответных сообщений ему не отправляется.

documentation/ru/docs/stylesheets/extra.css

@@ -1,13 +1,11 @@
-.md-typeset .admonition,
-.md-typeset details {
-    border-width: 0;
-    border-left-width: 4px;
-}
-
 .md-typeset .admonition, .md-typeset details {
     font-size: 0.75rem;
 }
 
+.md-typeset h1, .md-typeset h2 {
+    font-weight: 500;
+}
+
 @keyframes heart {
     0%, 40%, 80%, 100% {
         transform: scale(1);

documentation/ru/includes/abbreviations.md

@@ -1,2 +1,3 @@
 *[MR]: Merge Request
-*[БД]: База данных
+*[БД]: База данных
+*[Idea]: IDE IntelliJ IDEA

documentation/ru/mkdocs.yml

@@ -7,7 +7,7 @@ edit_uri: edit/develop/documentation/ru/docs
 
 nav:
   - О проекте: index.md
-  - Конфиденциальность: privacy.md
+  - Конфиденциальность: privacy/index.md
   - Возможности:
     - Уведомления: features/notify.md
     - Быстрые действия: features/interaction-gitlab.md