Куча нужен затем, чтобы создать обозримое поле (точнее, кучу) документов, над которыми работают или собираются работать участники ADT.
Куча должна быть централизованной, чтобы процесс разработки мог быть совместным и полностью открытым.
Куча должна быть доступна для открытого просмотра — это позволит любому сориентироваться в имеющихся материалах и свободно получать их для дальнейшей работы. См. раздел «Просмотр Кучи».
Размещение документа в Куче требует идентификации, поскольку представивший документ всё-таки несёт некоторую ответственность. См. раздел «Размещение документов в Куче».
Документы в Куче должны быть свободно распространяемыми.
Документы в Куче должны быть классифицированы: это позволит легче ориентироваться в том, на какие темы есть материалы. См. раздел «Классификация документов».
Документы в Куче должны сопровождаться паспортом, содержащим минимальное необходимое описание документа. О формате и содержимом паспорта документа см. раздел «Паспорт документа».
Помещает документы в Кучу «Автор» (см. раздел «Участники проекта»).
ВРЕМЕННО: В настоящее время Куча доступна по адресу ftp://ftp.altlinux.ru/pub/docs/Heap
В скором времени будет написан web-интерфейс для структурированного просмотра Кучи.
Для обратной совместимости данное полиси ещё некоторое время будет доступно по адресу ftp://ftp.altlinux.ru/pub/docs/adt_policy.tar.gz.
Для того, чтобы стать Автором, нужно сформулировать (кратко, но убедительно), что именно Вы хотите поместить в Кучу, и написать об этом по адресу joindocs at altlinux.ru. В этом письме нужно указать:
Идентификатор Автора (полное имя и псевдоним) — будет использован для авторизации при записи в Кучу и для идентификации его документов. Псевдоним не должен совпадать с уже существующими.
Действительный e-mail Автора, по которому члены ADT могут с ним связаться по поводу его документов.
Специально созданный OpenSSH-ключ (DSA, 2048 бит). На joindocs@ высылается публичная часть ключа. Этот ключ потребуется для помещения пакетов в репозиторий исходных текстов.
Если у Вас уже есть доступ в incoming/, то новый ключ не нужен, нужно только сообщить псевдоним, которым Вы пользуетесь для incoming/ (in_псевдоним).
Сгенерировать SSH-ключ можно командой ssh-keygen -t dsa -b 2048 -f файл_с_ключом, подставив на место файл_с_ключом имя файла. Настоятельно рекомендуется сделать ключ с паролем. На joindocs@ следует выслать публичную часть ключа (файл с расширением .pub).
Решение о предоставлении доступа и вся необходимая дальнейшая информация будут отправлены на адрес, указанный в письме Автора.
Напрямую поместить документ в Кучу невозможно, его нужно отправить в «точку входа» — incoming/docs. Для этого нужно сначала получить доступ на запись в Кучу, как это описано выше.
Incoming/docs — это временное пристанище, где хранятся вновь поступившие документы, пока они не будут проверены на соответствие правилам оформления (см. раздел «Оформление документа для Кучи»). Неправильно оформленный документ (отсутствует или оформлен не по правилам паспорт) не будет принят к размещению в Куче, а его отправитель получит письмо с сообщением об ошибках. Прошедшие проверку документы попадают в Кучу.
Получив доступ (учётную запись вида in_входное_имя), потребуется добавить в файл ~/.ssh/config
Host incoming
HostName cvs.altlinux.org
User in_имя
Protocol 2
ForwardX11 no
ForwardAgent no
Compression no
Для размещения в Куче документ нужно поместить в каталог incoming:/incoming/docs. Для этого лучше всего использовать rsync. Команда для копирования в incoming/docs может выглядеть так:
rsync -Pva --stats -e ssh имя_файла_документа incoming:/incoming/docs/
Если что-то непонятно или не получается, пишите на joindocs@ или в список рассылки ADT (см. раздел «Список рассылки»).
В Кучу принимаются документы в виде архива в формате .tar.gz, с единственным требованием: в корне этого архива лежат файлы с метаинформацией, а в подкаталоге с любым именем — сам документ. Допустимо всё содержимое архива поместить ещё в один каталог с любым именем.
Имя tar.gz-архива может быть произвольным, но должно быть записано латиницей и желательно, чтобы оно что-то говорило о документе. Нельзя помещать в Кучу разные документы под одним и тем же именем.
Обязательные файлы с метаинформацией:
Cодержит краткий паспорт документа. Правила оформления паспорта см. в разделе «Паспорт документа».
Содержит сведения об условиях распространения документа или название и версию лицензии, под которой распространяется документ.
Примеры tar.gz-архива:
Название файла:
имя_архива.tar.gz
Содержимое:
docinfo
License
подкаталог/
подкаталог/файлы_документа
Или: подкаталог/
подкаталог/docinfo
подкаталог/License
подкаталог/подподкаталог/
подкаталог/подподкаталог/файлы_документа
Паспорт документа для Кучи находится в файле docinfo в текстовом формате. Формат паспорта прост: он состоит из полей, каждое поле вида «название_поля: данные» и должно занимать одну строку. Проще всего сделать паспорт для своего документа при помощи интерактивной программы docinfo_gen.py (включена вместе с данным полиси в подкаталоге bin/, спасибо Дмитрию Аленичеву!). Для запуска программы требуется интерпретатор Python версии не ниже 2.2.
Паспорт можно составить также на основе примера (рыбы), см. файл examples/sample.docinfo. В этом файле все поля снабжены более развёрнутыми пояснениями, для получения правильного паспорта достаточно раскомментировать и заполнить нужные.
Всего полей около десятка, на их заполнение уйдёт совсем немного времени.
Классификация документов при помещении в Кучу нужна, чтобы Куча была не просто свалкой, и выпускающие, сопровождающие и остальная публика могли легко находить и просматривать документы на интересующие их темы. Документ классифицирует Автор, указывая нужные категории в паспорте. Список категорий определён заранее, его можно найти в файле examples/sample.docinfo, там же и пояснения.
Классификация включает 5 признаков, в каждом из которых 3—8 категорий. Желательно (хотя и не обязательно), охарактеризовать документ по каждому признаку. Можно (и зачастую нужно) по каждому признаку выбрать сразу несколько значений. Если по данному признаку не выбрано ни одно значение, считается, что документ попадает в «Прочее». Если документ вообще не отнесён ни к одной категории, он не будет принят к размещению в Куче.