Гарний README допоможе вашому проекту не потонути в океані open-source. В цій статті я розкажу про ключові пункти в README, які повинен мати кожен проект. Також в кінці є шаблон README.md ;)
Кожен день на GitHub публікують купу нових проектів. Наслідком цього стало те, що заявити про свій проект стало складніше. Підвищити свої шанси на увагу спільноти ви можете декількома способами, один із них — це скласти красивий і корисний файл README.
Давайте почнемо! Ось що повинен мати кожен README:
1. Що робить ваш проект
Ваші потенційні користувачі повинні мати змогу швидко зрозуміти, що за ПЗ перед ними і які функції воно виконує. Впевніться, що ця інформація присутня в самому початку файлу. Найкращими способами розказати про це буде короткий параграф, що описує ваш продукт і скріншот (а ще краще GIF), що показує ваш додаток в дії.
2. Як його встановити
Якщо людям сподобався ваш продукт, вони захочуть скористатися ним. Можливо, для вас встановлення власної бібліотеки і видається простим, але для інших це не так. Тому завжди пишіть інструкцію по встановленню.
Її відсутність відлякує потенційних користувачів. Зробіть цей крок настільки простим, наскільки це можливо. Гарним спосіб – написати блок коду, який показуватиме, що саме потрібно буде ввести користувачу в шелл, щоб встановити ваш додаток. Звісно, потрібно написати такий блок до кожної платформи, яку підтримує ваше ПЗ (OS X, Linux, Windows).
3. Приклад використання
Гарний приклад використання не менш важливий за зрозумілу інструкцію з інсталяції. Покажіть користувачам найкрутіші фічі вашого додатку. Я люблю робити це за допомогою декількох блоків коду з цікавими прикладами. Знову ж таки в цьому розділі вам потрібно вказати, що ввести в шелл чи натиснути в інтерфейсі, щоб побачити ваш додаток в дії.
4. Як встановити середовище для розробки
Так як ми говоримо про open source, дуже важливо допомогти розробникам вносити зміни в ваш проект. І першим кроком для цього є налаштування оточення для розробки. Гарним спосіб, як ви вже здогадались, – блок коду, що описує команди для розгортання цього оточення і запуску тестів.
Мати хоча б мінімальний набір тестів дуже важливо, це дозволяє розробникам впевнитись, що вони налаштували все правильно.
5. Як внести правку
Як я казав раніше, підтримувати хороший настрій у потенціальних контрибюторів дуже-дуже важливо. Тому, якщо комусь ваш проект сподобався настільки, що він розгорнув версію для розробки, вніс якісь змін, ви повинні просто і зрозуміло розказати йому як додати його правки в проект.
Ця секція повинна містити короткий опис вашого процесу розробки. Наприклад, приймаєте ви pull-request чи вимагаєте патчів через мейл, і все таке.
Також корисним буде описати як сформувати і випустити нову версію вашого ПЗ. Нехай, більшості ваших колег і не знадобиться це робити, але може статися різне, і буде неприємно, якщо це заважатиме розробці.
6. Список змін
Користувачі повинні знати чим відрізняються версії вашого додатку та чи слід їм оновлюватися. Я знаю, що для цього в GitHub'у є механізм релізів, але я лишаюсь прихильником окремого писка змін (change log) в README.
Одним з плюсів такого підходу є те, що його легко експортувати до репозитарію пакунків (таких як PyPI чи npm).
Зазвичай, я просто пишу список версій, де вказую ключові зміни в кожній з них. А ще тут можна згадати контрибюторів, що допомогли реалізувати ту чи іншу фічу. README — це перше, що бачить користувач, і було б непогано увіковічити тут людей, що зробили ваш додаток кращим.
7. Інформація про автора та ліцензію
Інформація про ліцензію та автора необхідна щоб прояснити юридичний статус продукта. Gitub рекомендує додавати файл LICENSE в головну папку вашого репозитарію. Але непогано буде також згадати це в кінці вашого README, а саме ваші контакти (наприклад, твіттер та мейл) та короткий абзац про ліцензування проекта.
README.md
Невеличкий шаблон, що допоможе вам не придумувати велосипед кожен раз.
# Product Name
> Short blurb about what your product does.
[![NPM Version][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Downloads Stats][npm-downloads]][npm-url]
One to two paragraph statement about your product and what it does.
## Installation
OS X & Linux:
sh
npm install my-crazy-module --save
Windows:
sh
edit autoexec.bat
## Usage example
A few motivating and useful examples of how your product can be used. Spice this up with code blocks and potentially more screenshots.
## Development setup
Describe how to install all development dependencies and how to run an automated test-suite of some kind. Potentially do this for multiple platforms.
sh
make install
npm test
## Release History
* 0.2.1
* CHANGE: Update docs (module code remains unchanged)
* 0.2.0
* CHANGE: Remove `setDefaultXYZ()`
* ADD: Add `init()`
* 0.1.1
* FIX: Crash when calling `baz()` (Thanks @GenerousContributorName!)
* 0.1.0
* The first proper release
* CHANGE: Rename `foo()` to `bar()`
* 0.0.1—
* Work in progress
## Meta
Your Name – [@YourTwitter](https://twitter.com/dbader_org) – YourEmail@example.com
Distributed under the XYZ license. See ``LICENSE`` for more information.
[https://github.com/yourname/github-link](https://github.com/dbader/)
[npm-image]: https://img.shields.io/npm/v/datadog-metrics.svg?style=flat-square
[npm-url]: https://npmjs.org/package/datadog-metrics
[npm-downloads]: https://img.shields.io/npm/dm/datadog-metrics.svg?style=flat-square
[travis-image]: https://img.shields.io/travis/dbader/node-datadog-metrics/master.svg?style=flat-square
[travis-url]: https://travis-ci.org/dbader/node-datadog-metrics
Ще немає коментарів