Нещодавно ми випустили інструмент з відкритим вихідним кодом GraphQL Voyager. Дивно, але він потрапив на першу сторінку новин Hacker News і GitHub, і в перші кілька днів отримав 1000 + зірок. Зараз у нього вже понад 1600 зірок. *
Людям сподобався гладкий інтерфейс, інтерактивні функції та анімація. Ми використовували TypeScript, React, Redux, webpack і навіть PostCSS, але це не ще одна стаття про це. Давайте заглянемо під капот...
Наша передісторія
Все почалося кілька місяців тому. Мій друг і я (ми називаємо себе APIs.guru) шукали ідею для проекту навколо GraphQL (мова запитів для API, розроблених Facebook). Після деяких досліджень нам попався на очі один цікавий інструмент - GraphQL Visualizer.
Ось що ми отримали на виході з GraphQL Visualizer:
Нам захотілося в нього додати:
- Кольори (чорно-біле виглядало занадто нудно)
- Масштабування
- Інтерактивні функції, такі як вибір вершин і ребер
Але, подивившись вихідний код, ми виявили фатальний недолік цієї штуки: там використовувався Graphviz - інструмент, розроблений десятки років тому, написаний на звичайному C і скомпільований в нечитабельний JavaScript з використанням Emscripten.
Виглядає навіть гірше, ніж те, що вилазить зазвичай з Uglify.js:
Як ми можемо використовувати щось з 2000-го року? Ми ж хіпстери, зрештою! ReactJS, D3, webpack, TypeScript, PostCSS - ось з чим ми працюємо! Не з інструментами, написаними на старомодному C .
Трохи покопавши, ми знайшли найкращу бібліотеку для вирішення цього завдання - Cytoscape.js. Вона написана на прекрасному JavaScript і навіть дозволяє застосовувати CSS-подібні селектори прямо до самого графу. Чудовий результат!
Але після тижня напруженого програмування він здався нам не таким вже хорошим.
Посудіть самі, ось як виглядає візуалізація графа з використанням Cytoscape.js:
І це ми навіть не відобразили на цьому графіку всі деталі! Що за мішанина!
Хоча код був набагато чистішим, кінцевий результат виявився набагато гіршим порівняно з оригінальним інструментом. Абсолютно неюзабільно.
Виявилося, що в cytoscape.js не можна зробити так, щоб ребра не перетиналися з вершинами графа. Ми перепробували всі варіанти. Ми гуглили. Ми ставили питання на StackOverflow. Ми навіть потурбували кількох знайомих гуру SVG. Безуспішно:(
Від безвиході я навіть спробував хакнути cytoscape.js, щоб домогтися читабельного результату. Ще трохи вивчивши це питання, я змушений був здатися: мабуть, візуалізація графів - це і справді rocket science (навіть для магістра з прикладної математики).
Ми були переможені...
І тоді нас осінило. А що, якщо ми візьмемо результат роботи Graphviz (адже це просто SVG) і причішемо його за допомогою CSS і JS?
І це спрацювало
Набагато краще! І код написаний менше, ніж за день 🕒.
Додаємо трохи кольору, логотип, завантажуємо анімацію, ще кілька корисних функцій, і ось кінцевий результат, те, що нам потрібно:
Так, ми написали кілька сотень рядків потворних маніпуляцій з DOM. Так, ми упакували весь цей бардак НЕ у вигляді чистого компонента React/Redux. І так, код Graphviz настільки великий, що ми виділили його в окремий файл розміром 2 МБ. Але це працює, і всім пофігу. Що підтверджується 1600 зірками на GitHub.
Апдейт: з моменту представлення статті часу нашу розробку взяли на озброєння компанії в цій області (наприклад, Graphcool, Neo4j), і її показали на GraphQL Europe, так що вже не тільки 1600 зірок підтверджують це:)
Уроки вивчені
«Якщо я бачив далі за інших, то тому, що стояв на плечах гігантів». - Ісаак Ньютон
Не судіть код за його віком. Особливо, якщо він був написаний такими технологічними гігантами, як AT&T Labs (де народилася ОС Unix і мови C і C++).
На жаль, ми виявилися жертвами когнітивного спотворення: старий код - це поганий код. Але правда може бути протилежною. Старий код перевірено в бою тисячами користувачів у сотнях різних проектів. Більшість критичних помилок були виправлені, документація завершена, є багато запитань і відповідей на StackOverflow і Quora.
Ми живемо в 2017 році, і користувальницький інтерфейс з 2000-х безумовно не прийнятний. Але графіки і математика, які стоять за ними, не сильно змінюються.
Ця ідея застосовна в багатьох інших областях. Так що ми повинні дати шанс старому коду, особливо тому, що його завжди можна обернути в сучасний інтерфейс.
Ось чому ми бачимо величезний потенціал в Web Assembly. Цей формат дозволяє з'єднати перевірені часом алгоритми з сучасними інтерфейсами користувача. Ми дуже хочемо побачити приголомшливі речі, які люди будуть на ньому робити.
"Емм... ти обіцяв мені розповісти, як отримати багато зірок "
Упс... Гаразд. Справді. Я хотів зробити заголовок досить пам'ятним.
Нижче наведено список найважливіших порад і трюків, які ми використовуємо для нашого проекту з відкритим вихідним кодом:
- Спробуйте використовувати назву своєї технології в імені проекту (наприклад, graphql-щось, react-щось тощо). Тоді ваш проект матиме вищий ранг у результатах пошуку GitHub для цих технологій.
- Ваш файл README повинен привертати увагу. Ми поклали гіфку в шапці нашого README, щоб люди могли відразу зрозуміти, про що йдеться в нашому проекті. Якщо це консольна програма - додайте гіфку з консіллю (ось чудовий приклад).
- Більше свистілок і перделок: додайте піктограми, додайте гарний логотип, додайте емодзі.
- Зберіть демо-версію, якщо це можливо, і додайте її до посилання в рядку з описом сховища:
- Повторюю, зробіть демку! І не забудьте додати посилання з нього назад на GitHub (ми використовуємо GitHub Corners).
- Перш ніж постити свій проект в HackerNews/Reddit/і т. д., отримайте початкове число зірок (5-10), розмістивши його на менш популярних ресурсах або поділившись ним зі своїми друзями. Люди з меншою ймовірністю натискають «зірку» на проектах з нульовим числом зірок.
- Спробуйте отримати 30-40 зірок у перший день. Тоді, вас, швидше за все, зафіксують в GitHub trending для вашої мови програмування, а це ще одне джерело трафіку.
- Зробіть щось корисне.
Є ще кілька статей про те, як просувати проекти з відкритим вихідним кодом: тут, тут і тут.
На цьому все, хлопці. Якщо ви коли-небудь загорнули старий код у новий блискучий інтерфейс, розкажіть свою історію в коментарях нижче.
* Примітка перекладача: через тиждень після оригінальної публікації у проекту вже 2000 + зірок.
Заголовна картинка, як і у вихідному пості, взята з сайту www.k3projektwheels.com.
