💾 Archived View for phreedom.club › ~tolstoevsky › tt › guidelines.gmi captured on 2023-01-29 at 17:36:01. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
Home
Главная /Main Манифест /Manifesto Лендинг /Landing Методичка /Guidelines
Итак, допустим, вы убеждены и хотите дополнительных инструкций о том, как помочь движению. Это именно тот документ, что вам нужен. Первые два раздела — короткие и рассказывают о том, как вы можете помочь, не разрабатывая собственное ПО в рамках ТТ. Третий раздел содержит указания по максимальному упрощению ПО, в попытке сделать его Тривиальным.
Новые возможности бесполезны, если люди ими не пользуются. Правда в том, что вы способны всё поменять. Если вас не устраивает положение дел в какой-то области попробуйте программу ТТ. Если вы всё ещё не удовлетворены — вам будет намного проще поменять всё под свои нужды, так попробуйте это сделать! Видите недовольство своих друзей — расскажите им о ТТ. Если вы знакомы с разработчиками — расскажите им о ТТ. Если вы знаете людей, чьи цели сходны с вашими — расскажите им о ТТ, пусть предложат свой вариант.
ТТ по своей сути Тривиальны. Они не могут быть централизованы. Например, эта инстанция, оригинальная она или нет, всего лишь зеркало. Ваше зеркало может содержать изменения, делающие его более пригодными для ваших нужд или нужд вашего сообщества. Всё это доступно под Unlicense, так что вам нет нужды беспокоиться о том, что вы делаете с идеей. Вот ряд рекомендаций по процедуре зеркалирования:
Скопируйте исходники (через git или просто как текстовые файлы).
Измените _footer.gmi, добавив туда ваши контактные данные в качестве сопровождающего.
Вычистите страницу external, если она существует и содержит данные.
Внесите изменения на своё усмотрение и разместите результат.
На страничке external по желанию можно сделать две вещи. Можно добавить список других известных вам зеркал — в этом случае вам может потребоваться поддерживать контакт с их сопровождающими. Второе — вы можете разместить список "сертифицированного" Тривиального ПО.
Процесс сертификации прост: попросите человека, не имевшего дела с этим ПО, пополльзоваться им на протяжении выходных (суть требования про "два дня"), пусть попробует понять это ПО полностью, включая API зависимостей, всю лицензию и мета-знания (как собрать и запустить это ПО). Если вы не можете найти подобного человека, найдите технаря, но в этом случае требование по времени сокращается в 8 раз (до шести часов). Это гораздо более жёсткое требование. Ну и, разумеется, вы не можете сертифицировать собственные проекты.
Людям, просматривающим список сертифицированных проектов, рекомендуется самостоятельно проверять эту сертификацию, и, возможно, добавить свой список. Варианты, когда кто-то просто сертифицирует всё, что пожелает, включая свои собственные рпокты, должны быть очевидными — в этом случае зеркало стоит просто игнорировать, просто ввиду недобросовестности сопровождающего.
Первый шаг прост — вы должны пожелать, чтобы ваш проект был Тривиальным. Если у вас есть подобное желание, вставьте фразу об этом в README, заявляя миру, что ваш проект стремится достичь стандартов движения ТТ, и ссылку на зеркало по вашему выбору (ссылка должна вести на страницу лендинга). Всё остальное имеет невеликое значение, если вам удастся достичь указанных стандартов. Всё остальное — не более, чем рекомендации.
Ваши коммиты должны быть минимальными и объяснять причину вносимых изменений.
Оставляйте комментарии в местах существенных изменений.
Всё, что объявлено глобально, должно быть read-only для всех модулей, в которых оно объявлено. Изменения вносятся в стиле библиотек или в main. В этом случае указывайте на это в комментариях.
Функции и типы должны быть логичными и ограниченными. Ни в коем случае не создавайте функцию, делающую множество вещей.
Минимизируйте количество аргументов. Если у функции 10 аргументов — проверьте, почему их столько и не стоит ли их перегруппировать в reusable type.
Минимизируйте вложенность и потоковые функции. Поддерживайте несколько уровней отступов. Если вам нужно настраиваемое поведение, подумайте о map/reduce и о visitor pattern. Функции высшего порядка хороши, если их использование понятно.
Поддерживайте файл NEWS. Он должен быть последовательным и содержать только изменения, видимые пользователю.
Поддерживайте файл READING. Он должен содержать информацию о том, как читать исходники, в каком порядке и мягко помогать читателю разобраться в вашей программе.
Минимизируйте объём и ограничения лицензии в файле LICENSE, так как полное понимание этого файла — часть понимания вашего проекта. Мы рекомендуем Unlicense и 0BSD.
Минимизируйте количество "мета-работы". Проект, использующий CMake, требует от читателя понимания CMake. Это лишнее переключение контекста сильно увеличивает сложность понимания проекта, особенно, когда мета-работа разрастается до сотен строк. Предпочитайте либо очень малый объём мета-работы (простой makefile или скрипт) или языки, не требующие оной (например Go, где вся дополнительная работа сводится к build-flags, число которых должно быть минимальным).
Добавляйте только те функции, которые используете лично вы. Вместо добавления всех фишек — просто оставьте открытые места, где каждый сможет расширить функциональность под себя. Если вы не используете какую-то фичу сами, вы не знаете, как другой может захотеть её использовать, так что просто позвольте им сделать это самим, для их собственных нужд.
Maintained at gitea.phreedom.club/tolstoevsky/tt by Tolstoevsky