# Описание проекта #

## Зачем? ##
Работа над сбором чувашской топонимики заинтересовала нас в контексте решения задач более высокого уровня -- реконструкции языковой и этнической истории Поволжья и Прикамья. Это накладывает отпечаток на выбор источников данных, технические и прочие решения. Мы стремимся учесть доступные топонимические данные всех релевантных языков и временных срезов, что могут быть полезными для решения конечных задач.

## Что за источники данных? ##
Для сбора данных мы хотим инвентаризировать доступные источники:
- книги
- карты
- данные Росреестра
- прочее?

## Как планируется структурировать получаемые данные? ##
Навскидку, работа видится примерно так:
- есть сводная таблица найденных источников
- для каждого источника составляется таблица с упомянутыми в нем топонимами
- составляется общая таблица топонимов и общая таблица объектов (города, реки, деревни, урочища, ручьи и т.д.), которые можно восстановить по имеющимся данным
- для объектов даются ссылки на все их известные названия (собственно, топонимы) на всех языках в общей таблице топонимов
- в таблице объектов кроме названий дается информация о их местонахождении (координаты и пр.), времени бытования топонима и т.д.
- отдельно идет работа над таблицей с метаданными о топонимах: этимология, комментарии, прочее

Итого 4 таблицы (источники, топонимы, объекты, метаданные) + по 1 таблице на каждый источник данных.

## Как все это будет организовано с технической точки зрения? ##
На данном этапе вопросов больше, чем ответов. Тем более, что в начале проекта обычно не очень понятно, какой объем внутренней бюрократии достаточен для достижения целей.
Мои (RI) представления о полезном и прекрасном базируются на опыте участия в долгосрочном лексикографическом проекте: словарь бесермянского диалекта удмуртского языка, http://beserman.ru/ -- если сайт в данный момент не открывается, то это очередное напоминание о рисках, связанных с чужими серверами.
Словарному проекту на текущий день 21 год, я участвовал в проекте примерно треть этого времени и имел возможность увидеть последствия продвигаемых мной технических и организационных решений.
Одним из главных для меня выводов из многолетнего бесермяноведческого опыта стало осознание важности доступа к полной истории проекта.
В глоссарии проекта Fossil (https://www.fossil-scm.org) дано такое определение проекта -- "A collection of one or more computer files that serve some conceptually unified purpose, which purpose changes and evolves over time, with the history of that project being a valuable record".  
Я не могу наперед знать, что именно окажется важным для проекта в будущем, поэтому я хочу хранить подробную историю изменений проекта и я готов жертвовать своим удобством ради доступа к истории.

## Что важнее: удобство или бюрократия? ##
TLDR: информация не должна теряться.
Если более подробно, то бюрократия в долгом проекте необходима, потому что 1) люди совершают ошибки, 2) человеческая память несовершенна.  
Хранение всех изменений в системе контроля версий позволяет всем участникам:
1) иметь полный доступ к истории проекта
2) быть уверенными, что они помнят одно и то же и говорят об одном и том же, будь то мельчайшее изменение или общая картина
3) исправлять случайные ошибки
4) понимать, кто является ответственным за любое изменение
5) не делать одну и ту же работу несколько раз
6) всегда иметь доступ к свежей версии файлов проекта и т.д.

## Каково пространство технических решений? ##
Технические решения, принятые в начале работы, сильно влияют на возможную схему организации проекта.
Так, работу над таблицами можно вести в:
- MS Excel. Файлы .xlsx вполне можно хранить в fossil- или git-репозитории и тогда всегда будет ясно, кто над какой версией файла работал. Это не очень удобная схема, но возможная.
- Google Sheets. Все причастные сразу видят все внесенные изменения, история проекта, пусть и не в самом удобном виде, тоже доступна. Это самая удобная схема для повседневной работы.
- базе данных Sqlite или Postgres. Их тоже можно версионировать, например, с помощью софта типа https://github.com/dolthub/dolt Но это повышает требования к технической экспертизе участников и привязывает к сложным посторонним программам, будущее которых туманно.
- csv-файлах. Их можно редактировать с помощью Excel, Google Sheets, плагинов к популярным текстовым редакторам типа https://marketplace.visualstudio.com/items?itemName=janisdd.vscode-edit-csv или специальных текстовых редакторов типа http://home.hccnet.nl/s.j.francke/csved/unicsvedsetup.exe Это, по моему мнению, самая удобная схема с точки зрения простоты доступа к полной истории проекта, хотя и не самая удобная для повседневного редактирования таблиц.
Схемы можно комбинировать, например, никто не мешает держать регулярно обновляемую read-only версию всех таблиц на Google Sheets и вести основную работу в csv-файлах.
За кадром остаётся куча всяких более мелких вопросов, типа того, например, как в каждом случае можно организовать проверку на уникальность объектов в таблице, чтобы не возникало повторов и прочее в том же роде. Их тоже стоит в какой-то момент обсудить.
Для организации хранения информации о проекте, включая полную историю проекта, предлагаю использовать уже упомянутый Fossil (https://www.fossil-scm.org).  
Fossil это продвинутое средство управления программными проектами, он включает в себя:
- систему контроля версий
- вики
- баг-трекер
- форум и прочее
Ко всему этому прилагается веб-интерфейс и CLI (подробнее см. https://www.fossil-scm.org/home/doc/trunk/www/quickstart.wiki).

## Какие возможны роли у участников проекта? ##
Моя (RI) точка зрения такая, что у топонимических данных есть жизненный цикл и устроен он примерно таким образом:
- поиск и ввод данных (data entry)
- обзор данных (data review)
- редактирование данных (data editing)
- анализ данных (data analysis)
- публикация данных (data publishing)
- еще что-то?
В роли data entry person может выступать кто угодно после первичного обучения, а последующие роли (reviewer, editor, analyst, publisher) требуют большей экспертизы.  
Поэтому интерфейс ввода данных может отличаться от интерфейсов для остальных ролей, например, результат обработки первичных данных мы вводим в Google Sheets, далее там же проводим этап review и этап editing. Затем импортируем в Fossil эти табличные данные, скажем, в CSV или TSV формате, с прикрепленными метаданными, типа, кто вбивал исходные данные, кто выступал ревьюером, кто редактором, когда это было и т.д. Затем в какой-то момент экспортируем из fossil-репозитория некоторое подмножество данных для анализа, преобразуя при этом хранящийся в репозитории CSV-файл в какую-то базу данных (Postgres, sqlite3 etc). Естественно, текстовые данные, хранящиеся в репозитории, можно редактировать в любой момент, например, по итогам какого-то анализа или после более глубокого ревью.

## Как работать в fossil? ##
Сейчас файл репозитория проекта доступен по адресу: https://sjyrmi.ru/myfossil/chu_toponymy_1
После установки fossil на свой рабочий компьютер, можно клонировать этот репозиторий с помощью команды clone:
fossil clone https://<имя пользователя>@<имя сервера>/<путь>/<к файлу>/<репозитория> ./<локальное имя файла репозитория>.fossil

При этом лучше сразу создать директорию для последующей работы:
mkdir top_fossil_repos
cd ./top_fossil_repos

Обычно при клонировании надо указывать имя пользователя (и сразу после этого пароль), например, так:
fossil clone https://santor@sjyrmi.ru/myfossil/chu_toponymy_1 ./chu_top_fossil_repo.fossil

Если всё прошло удачно, то после этого можно открыть файлы из репозитория:
fossil open ./chu_top_fossil_repo.fossil

То, что показано выше, распаковывает файлы проекта прямо в текущую папку. Это не всегда удобно, можно организовать работу иначе.
Например, можно создавать для работы над разными файлами разные папки:
mkdir ./data_entry
cd ./data_entry
fossil open ../chu_top_fossil_repo.fossil
cd ..
mkdir ./data_analysis
cd ./data_analysis
fossil open ../chu_top_fossil_repo.fossil

После окончания редактирования файлов надо добавить все файлы, изменения в которых важны:
fossil add ./file_1.csv ./file_2.csv
и сделать коммит с описанием сделанных изменений:
fossil commit -m "add ~360 new river entries from ru.chuvash.org"

После этого информация о том, кто, когда и какие изменения внес в файлы проекта, будет сохранена и в локальную версию репозитория, и на сайт, откуда был склонирован репозиторий.

## Как можно увидеть историю изменения таблиц проекта? ##
<a href="https://sjyrmi.ru/myfossil/chu_toponymy_1/wiki?name=How+to+view+tabular+document+difference&p">Краткое описание смотри в этой вики-статье</a>

## Что сейчас находится в репозитории проекта? ##
Не очень много:
bin/daff.exe	-- утилита для просмотра изменений табличных данных (см. подробнее https://paulfitz.github.io/daff/)
data/csv		-- результат экспорта исходной таблицы из формата Старлинга в csv, совместимый с MS Excel (в качестве разделителя используется знак ';', кодировка UTF-8 with BOM)
data/demos		-- csv-файлы, на которых удобно тренироваться работать с bin/daff
data/img		-- сюда можно складывать скриншоты и прочие картинки для статей
data/starling	-- здесь лежат исходные файлы, с которыми santor работал в программе Старлинг (https://starlingdb.org/program.php?lan=ru)
DESCRIPTION.md	-- развернутое описание проекта
README.md		-- краткое описание проекта