«Начало — более чем половина всего».
Это очень древний
Мне довелось сочинить более десятка модулей для Node.js с открытым исходным кодом и опубликовать их в качестве пакетов npm. Чем больше модулей я делал, тем сильнее понимал (в том числе путём проб и ошибок), что начальные шаги для их создания могут быть одинаковыми и даже могут совершаться в одном и том же порядке. Сегодня я публикую этот порядок в надежде на то, что он станет подспорьем в работе программистов, сочиняющих свой код на языке JavaScript для движка Node.
Обратите внимание на то, что каждый из этих шагов довольно прост и логичен.
Шаг 1. Придумывание имени пакета npm и репозитория.
Без имени ничего не получится. Не имея имени для своего проекта, вы не сможете создать для него ни репозиторий на Гитхабе, ни пакет npm.
Заранее убедитесь в том, что имя пакета npm ещё не занято. (Вот пример: если осенью вам вздумается назвать свой пакет «autumn»
Если именем вашего пакета npm послужит
А короткое ли будет имя у вашего пакета npm или длинное? Если короткое, то его проще вручную набрать (например, в командной строке после
Для модулей, наделённых слишком длинными именами, рост ширины такой гистограммы может вызвать (и вызовет, непременно вызовет!) необходимость размещения статистики на отдельной строке, а не справа или слева
Шаг 2. Придумывание краткого описания.
Краткое описание пригодится и при создании проекта на Гитхабе, и позднее (например, при заполнении поля description в файле
Лучше всего поместить туда всего одно краткое предложение с описанием того, что делает ваш модуль. Оно будет способствовать поисковой находимости и сопутствовать названию пакета или репозитория на многих сайтах с гиперссылками. Если сделать описание слишком длинным, то оно не поместится на карточку в Твиттере (и на других сайтах, обрезающих описания по длине); кроме того, даже если поместится, то при беглом чтении списков публика всё равно не станет дочитывать до конца его.
Шаг 3. Создание репозитория на Гитхабе с автоматически заполненным README-файлом.
Как правило, репозитории модулей Node создаются на Гитхабе; мне попадались и исключения из этого правила, но редко. Поэтому все шаги я стану здесь излагать с расчётом на употребление Гитхаба и Git, а читателям из числа пользователей других DVCS
На странице
Когда в репозитории на Гитхабе с самого начала есть хотя бы один файл, то репозиторий можно просто клонировать (например, командою
Но автосозданный Гитхабом файл лицензии зачастую приходится править под себя (например, вместо гитхабовского логина указывать своё полное имя или название организации), да и в автосозданный
После создания репозитория на Гитхабе не позабудьте внести все те изменения в настройках репозитория, которые считаете необходимыми для него. Например, если мало времени и поэтому некогда приглядывать за вики, то можно отключить в репозитории поддержку вики. А если, например, вы привыкли видеть в списке «Starred» (в списке репозиториев, помеченных звёздами) не только некоторые чужие репозитории, но и все свои репозитории, то тогда можно тотчас же поставить свежесозданному репозиторию его первую звезду.
Шаг 4. Добавление текстового файла с указанием лицензии.
С этим шагом лучше всего не затягивать: чем раньше вы дадите понять, под какою лицензией распространяются все последующие правки, тем лучше.
Как я и говорил на предыдущем шаге, если вы создаёте не первый модуль Node в своей жизни, то можно скопировать
Если же вы в первый раз принимаете решение о том, под какой лицензией распространять свой открытый исходный код, то можете последовать примеру сообщества (а в сообществе Node.js, насколько я могу судить, лицензия MIT наиболее популярна, хотя встречаются и исключения из этого правила), или проконсультироваться с сайтом
Шаг 5. Добавление файлов .gitignore и .npmignore.
Как известно, в файле .gitignore перечисляются имена тех файлов и каталогов, которые не должны попадать в репозиторий Git, потому что они только напрасно захламляли бы его. К их числу относятся, как правило, архивы и дистрибутивы проекта, логи, базы данных, вспомогательные файлы операционной системы (например, хранилища миниатюр изображений, содержащихся в некотором подкаталоге).
При разработке проекта, в котором один или несколько модулей Node используются в качестве зависимостей, бывает вполне уместно добавить в файл .gitignore имя каталога
(Для расширения кругозора упомяну, что Mikeal Rogers высказывал и деятельно продвигал совершенно противоположную рекомендацию. Но это случилось
Также в файл .gitignore полезно добавить имя отчёта
В итоге файл .gitignore приобретает
# Архивы, дистрибутивы *.7z *.dmg *.gz *.iso *.jar *.rar *.tar *.zip # Базы данных, логи *.log *.sql *.sqlite # Спецфайлы операционных систем Thumbs.db Desktop.ini .DS_Store* ehthumbs.db Icon? # Модули Node, логи npm node_modules npm-debug.log
Файл .npmignore примерно аналогичен файлу
Я рекомендую скопировать
Как правило, начиная работу над новым модулем Node, можно скопировать файлы .gitignore
Шаг 6. Описание модуля в README.md, упоминание о лицензии и о неоконченности разработки.
Напоминаю, что на третьем шаге был автоматически создан файл README, состоящий только из названия и краткого описания модуля.
Теперь это описание можно несколько пополнить, рассказав о целях и задачах проекта. Кроме того, в отдельном подразделе описания уместно упомянуть тип лицензии (например, MIT или BSD) и имя того файла (как правило,
Чтобы попытки практического знакомства читателей с возможностями модуля на этом этапе не вызывали разочарования (а ещё лучше — чтобы такие попытки вообще пока что не происходили), полезно сразу вывесить предупреждающее упоминание о том, что разработка модуля не только не закончена, но и находится на самой ранней стадии.
После такого пополнения файл README годится в качестве первоначального описания первоначальной версии
Однако, если вам довелось упомянуть в README ещё и планируемое имя пакета, то не торопитесь помещать результаты этого шага в репозиторий (например,
Вообще же рекомендую считать, что на этом шаге упоминать в README планируемое имя пакета было бы рановато.
Шаг 7. Сочинение package.json и регистрация пакета npm самой начальной версии.
Конечной целью этого шага является регистрация
Начать такой шаг приходится созданием файла package.json и заполнением сразу нескольких полей объекта внутри него. При этом надо одновременно соблюдать формат JSON и то описание смысла полей, которое приведено
Существует команда «npm init», которая задаёт вам вопросы о модуле и самостоятельно заполняет package.json в соответствии с ответами. Однако я предпочитаю заполнять package.json в текстовом редакторе — это позволяет обозревать весь код JSON в чистом виде (не разбавленный вопросами) и притом даёт простую возможность возвратиться на пару строк выше, чтобы подправить или переменить
Вообще-то документации, лежащей
Значением для поля «name» указывается желаемое имя пакета npm. Его вы могли придумать ранее (на первом шаге).
Значением для поля «version» указывается версия пакета в соответствии со стандартом Semantic Versioning. Для регистрации самой начальной версии я рекомендую
Значением для поля «description» указывается краткое описание пакета. Его вы могли придумать ранее (на втором шаге).
Значением для поля «keywords» указывается массив ключевых слов, по которым пакет могут отыскать в поиске по сайту npm. Всякий, кто
Значением для поля «license» указывается строка-идентификатор, соответствующая стандарту SPDX ID и означающая лицензию, выбранную вами для своего кода ранее (на четвёртом шаге).
Значением для поля «author» указывается строка (или объект) с именем автора пакета (а также, может быть, с контактными данными). Укажите там себя.
Значением для поля «repository» указывается объект, содержащий тип и адрес репозитория.
Значением для поля «main» указывается путь к главному файлу кода модуля (это тот самый файл, который из Node будет вызван функцией
Если модуль подразумевается как утилита, работающая из командной строки, то тогда такому модулю полезным будет
Код модуля на этом шаге может быть простейшим — например, содержать
В описание коммита уместно поместить фразу «пакет зарегистрирован» (или «пакет опубликован») и совершать этот коммит только после того, как команда
Шаг 8. Объяснение установки в README.md.
Во время этого шага уместно поместить в файл README.md объяснения, сообщающие будущим пользователям смысл двух команд:
- npm install имяПакета — команда, которая установит
npm-пакет из хранилища npm,
- npm install https://github.com/имяПользователя/имяРепозитория/tarball/master — команда, которая установит модуль
из master-ветки гитхабовского репозитория.
Также полезно объяснить будущим пользователям разницу между результатами той и другой команды — например, рассказать о принятом ранее (на пятом шаге) решении хранить тесты только на Гитхабе, а не в npm (чтобы не увеличивать объём
Можно ещё рассказать, что и последняя версия файла README.md будет только на Гитхабе (если только вы не планируете создавать и публиковать очередную новую версию своего
Во время этого же шага можно также получить на сайте
Шаг 9. Самое начало работы над основным кодом модуля.
На этом этапе зачаток модуля (то есть
По мере формирования все эти возможности исходного кода следует аккуратно документировать в README.md, чтобы единственной документацией к открытому исходному коду не остался сам код.
Кроме того, как только исходный код достигает этой стадии, так сразу его становится неплохо бы покрыть тестами, проверяющими корректность кода и его поведения. Об этом — следующий шаг.
Шаг 10. Содействовать тестированию и объяснить его.
На этом шаге надобно поместить в README.md понятные сведения о том, как установить и как использовать средства тестирования правильности написания исходного кода (например, JSHint) и его поведения (например, Mocha).
На этом этапе в репозиторий также добавляются конфигурационные файлы для средств тестирования (например,
В объекте внутри файла
Пример:
"scripts": { "pretest": "jshint имяМодуля.js test/", "test": "mocha --reporter spec --timeout 60s" }
Начиная от этого шага, перед каждым коммитом желательно убеждаться в том, что команда
Шаг 11. Конфигурирование Travis CI.
Travis CI — это сервис, предоставляющий услугу бесплатного тестирования открытого исходного кода: после каждого коммита он способен автоматически скачивать код с Гитхаба и запускать тесты в различных окружениях, чтобы посмотреть, хорошо ли работает код.
К первоначальному употреблению Travis CI неплохо бы подготовиться, то есть прочесть документацию и пройти регистрацию.
Подключение же нового джаваскриптового модуля гораздо проще и состоит из двух несложных шагов.
Во-первых, надо зайти по адресу https://travis-ci.org/profile/ в свой пользовательский профиль. Там появятся переключатели, каждый из которых соответствует одному из репозиториев на Гитхабе; выглядит это
Переключатель, соответствующий новому модулю, следует дёрнуть во включённое положение.
Во-вторых, сразу после этого надо закоммитить файл
language: node_js node_js: - "0.10" - "0.12" - iojs before_install: - "npm install -g npm" - "npm config set spin false" before_script: - "npm install jshint" - "npm install mocha"
В разделе «language» вы видите указание «языка» (точнее, движка) Node, а в разделе
В разделе «before_install» приведены команды, обновляющие npm до последней стабильной версии, а также отключающие анимацию крутящегося курсора (которая в логах Travis CI всё равно не отображается, так что нечего тратить на неё время).
В разделе «before_script» приведены команды, устанавливающие средства тестирования (в этом примере — JSHint и Mocha).
Шаг 12. Добавление индикатора Travis CI в README.md.
Travis CI предоставляет URL картинки, которую можно поместить один раз в README на Гитхабе и затем всякий раз видеть там, успешно ли прошло на Travis CI тестирование итогов последнего коммита.
На сервере shields.io предоставляется возможность получить несколько другую форму этой картинки — например, изменить объёмность, или закругление краёв, или часть надписи.
Обобщение метода.
Здесь заканчивается список простых начальных шагов разработки модуля
Понятно, надеюсь, что такой метод (то есть возможность придать себе первоначальный импульс, начав работу с воспроизведения ранее подготовленных шагов) годится не только при разработке модулей для Node.
Приведу пример. В статье про паралич разработчика (которую PerseptronYar перевёл) вы могли видеть на Хабрахабре рассказ о том, что всякий современный сайтостроитель, приступая к работе, без промедления оказывается перед неотступною необходимостью раз за разом делать неочевидный выбор между различными возможностями примерно равной привлекательности — наподобие буриданова осла:
Starting a basic website in 2014:
1. Install Node
2. Install Bower
3. Pick CSS framework
4. Pick responsive approach
…
47. Write some HTML
— I Am Devloper (@iamdevloper) 2 октября 2014
Вы можете, однако, сильно упростить себе жизнь в дальнейшем, если сумеете не только один раз сделать такой выбор, но и в дальнейшем попросту придерживаться его. Для этого достаточно зафиксировать в письменном виде выбор, сделанный на каждом таком шаге, записать все эти шаги в их готовом виде (то есть, например, не «выбрать CSS framework», а «установить Bootstrap», если выбрали Bootstrap), а затем следовать им при начале каждого нового проекта, если только в промежутке между проектами не объявился повод сознательно попробовать
ссылка на оригинал статьи http://habrahabr.ru/post/262057/
Добавить комментарий