LotusTM development workflow

В данном документе описаны основные принципы разработки в среде команды LotusTM

Термины и транслитерация

<placeholder>

IDE

Для разработки может использоваться любой IDE, однако важным требованием является поддержка EditorConfig для сохранения консистентности отображения и редактирования файлов в рамках данной рабочей среды.

Git

Для версирования используется Git.

Основными средствами для работы с Git являются SmartGitHg и GitHub.

Scaffolding

Репозитарий имеет структуру следующего вида:

├── build
│   ├── assets
│   │   ├── fonts
│   │   ├── images
│   │   ├── sprites
│   │   ├── scripts
│   │   └── styles
|   ├── index.html
|   └── ...
├── source
│   ├── boilerplates
│   ├── fonts
│   ├── images
│   ├── layouts
│   │   └── *.nj
│   ├── scripts
│   │   └── *.js
│   ├── styles
│   |   └── *.scss
├── ...
├── .editorconfig
├── .gitignore
├── package.json
└── README.md

* как правило, бинарные и медиа ассеты вынесены на поддомен и подключены субмодулем для оптимизации процессов деплоя и уменьшения размера основного рабочего репозитария

Ветки

Во время разработки в среде Git используются две ветки:

• develop — основная ветка для проведения разработок. Любые изменения кода должны производиться именно в этой ветке;

• master — ветка для production-версии приложения, которая автоматически разворачивается на production-сервере и содержит только релизы. За коммит в master-ветку будут отрезаться руки и убиваться невинные котики.

При необходимости можно применять методологию GitFlow.

Коммиты

Все коммиты должны быть написаны:

1. на корректном английском языке;
2. в прошедшем времени;
3. преимущественно прописными буквами;
4. с корректной пунктуацией;
5. без точки в конце.

Все коммиты должны содержать следующие структурные элементы в линейном порядке:

1. дефис и пробел: - ;

2. инлайн-тэг или инлайн-тэги вида [html];

3. пробел;

4. краткое описание изменений в коммите с маленькой буквы и без точки в конце;

5. в случаи наличия референса к определенной задаче в Redmine — отделенные от описания коммита запятой статус и номер задачи в виде , fixes #123.

   Issue-трекер принимает следующие статусы:

   • ref #123 или ref,refs,references,issue — устанавливает связь между коммитом и задачей;
   • fix #123 или fix,fixes,fixed,closes,closed — отмечает указанную задачу решенной.

В результате коммит будет иметь следующий вид:

- [html] removed IE conditional comments, fixes #123

Инлайн-тэги используются для дифференциации коммитов в репозитарии.

В большинстве случаев инлайн-тэг должен содержать расширение файла или файлов, которые были изменены. Исключением являются файлы .scss, для которых инлайн-тэгом является [sass].

В случае комплексных изменений определенных групп, когда разделение на меньшие коммиты является необоснованным, с целью выделить отношение данных комитов к определенной группе могут использоваться инлайн-тэги, которые содержат названия таких груп в строчном виде.

Список зарезервированных наименований для групп:

• [git] — для изменений в файлах Git;
• [craft] — для изменений в файлах Craft CMS;
• [sass-framework] — для изменений в файлах SASS Framework;
• [submodule] — для изменений в субмодулях;
• [misc] — для общих изменений;
• to be continued...

Кроме того, в случаях комплексных изменений, с целью не потерять целостность работы и подчеркнуть тот факт, что коммит содержит монолитные изменения, при разделении которых может быть утрачена целостность картина, в одном коммите могут использоваться несколько инлайн-тэгов без разделения их пробелами. Например, [html][sass].

Для обновлений субмодулей должен использоваться инлайн-тэг [submodule] и тэг элемента, который обновляется. Например, [submodule][sass-framework].

Для обозначения любых изменений в репозитарии, связанных с перемещениями, переименованиями, а также работой с любой документацией должен использоваться инлайн-тэг [misc].

Элементы или блоки верстки, кода и подобные наименования должны быть выделены ` с двух сторон. Например `index-header`. Классы или переменные, несущие перед собой идентифицирующий элемент могут писаться без подобного выделения. Например, .index-header или $some-variable. Такой подход позволяет, например, отличить блок html-кода с определенным наименованием от класса с идентичным наименованием из CSS.

В случае необходимости, после краткого описания изменений в коммите могут быть приведены важные заметки или предупреждения разработчика. Заметки должны отделяться от основной части коммита точкой начинаться с NOTE:, а предупреждения — с CAUTION:.

К примеру

- [html] removed IE conditional comments. CAUTION: no more IE6-7 support

В заметках и предупреждениях должна содержаться только действительно важная информация для данного коммита. В ином случае следует использовать issues-трекер.

Бинарные файлы

В большинстве случаев в репозитарии предусмотрен специальный субмодуль для ассетов, потому прежде чем делать коммит с любым видом бинарных файлов — убедитесь, что конвенцией по работе с данным репозитарием это разрешено. Если Вы не уверены куда корректней в данном случае запушить такой файл — уточните этот момент у лида.

Тэги

Git-тэги используются только для определения версии релиза с применением Semantic Versioning 2.0.0.

Устанавливаются только продукт-менеджером.

Issues-трекер

В качестве issues-трекера используется Redmine

Трекеры

В процессе работы используется 3 типа трекеров:

• Feature — предназначен для первоначальных разработок. Все, что создается с нуля, должно быть помещено в данный трекер;

• Improvement — предназначен для улучшений и доработок уже существующих элементов/объектов/кода, даже если они подлежат полному изменению;

• Bug — предназначен для трекинга именно ошибок. Любые задачи касательно доработки или устранения недоработок должны быть помещены в трекер улучшение.

• Support — предназначен для трекинга задач, поступающих из внешней среды (например, пользователей, руководства, сотрудников), а также для любых задач, не связанных с разработкой сайта или приложения напрямую.

Roadmap

Для разделения работы на критические этапы работы используется roadmap в Redmine:

• *stage-name* — обозначение вех работ.

  В качестве наименований вех используются Semantic Versioning 2.0.0

  В каждую веху включается план задач на 1 этап работ.

• backlog — содержит все фичи, улучшения или изменения, которые не входят ни в один из этапов запланированных работ. Служит бэк-логом. В последствии фичи из данного roadmap должны быть перенесены в один из запланированных этапов, или же отклонены и закрыты.

В зависимости от важности задачи создаются либо в рамках текущего roadmap, либо в backlog.

Задачи

Задачи создаются продукт-менеджером, а в случае поступления задачи через иной коммуникационный канал (email, skype) — самим исполнителем.

Назначение исполнителя для задачи является обязательным за исключением ситуаций, когда еще неизвестно кто будет являться исполнителем настоящей задачи.

Заголовок задачи должен коротко, но ясно описывать суть задачи.

Описание задачи является ситуационным.

Кроме того, каждая задача должна:

1. быть помещена в соответствующий трекер;
2. быть помещена в соответствующий roadmap;
3. относиться к определенной родительской задаче, если таковая имеется;
4. содержать соответствующую категорию;
5. иметь соответствующий статус.

Категории задач

Для дифференциации задач используются следующие категории:

• Assets — фото, тексты и так далее;
• Backend — любой вид кодинга, связаный с backend, , темплейтинг backend;
• Design — дизайн любого типа;
• DevOps — все что связано с DevOps;
• Frontend — любой вид кодинга, связаный с frontend, , темплейтинг;
• Markup — верстка html-кода;
• Prototyping — прототипирование макетов, интерфейсов;
• Research — для обозначения любых ислледовательских, проектных и предпроектных задач;
• Server — любые работы с сервером;
• Workflow — git, github, конфигурация репозиториев и среды разработки и любых задач организационного характера;
• без категории — задачи, которые не могут быть отнесены к определенной категории или будут отнесены к какой-то категории позже, а также ошибки, у которых нет четкого характера.

Группирование задач

Комплексные задачи должны быть сгруппированы. Для этого используется родительская задача с общим описанием задачи, к которой прикрепляются дочерние задачи с описанием конкретных задач по данном тикету.

Родительской задачей всегда является фича или ошибка, которая может иметь дочерние задачи с разными категориями.

Задачи могут быть свзяаны между собой релейшенами

Как правило, в рамках roadmap по умолчанию создается следующая структура, которой следует придерживаться:

├── Фича
│   ├── комплексный элемент фичи
│   │   └── перечень работ по данному элементу
│   └── любые задачи касательно данной фичи, которые не являются комплексными
└── задачи, которые не входят ни в одну из выше перечисленных групп
    └── подзадачи

Задачи, у которых есть несколько исполнителей, разбиваются на задачи с указанием конкретных задач для каждого исполнителя и присоединяются к общей основной задаче в качестве дочерних задач.

Статусы задач

В момент создания задаче выставляется статус Новый

В момент начала работ над данной задачей исполнитель выставляет ему статус В работе. Данный статус сохраняется до полного решения данной задачи или её отклонения.

В случае необходимости получения комментария по задачей ей выставляется статус Обратная связь до момента получения обратной связи.

В результате решения задачи исполнителем выставляется статус Решена.

В случае если задача по каким-либо причинам не может быть решена или должна быть отклонена, ей выставляется стутс Обратная связь с указанием причины отклонения.

Статус Закрыта или Отклонена выставляется только принимающей стороной (как правило, продукт-менеджером).

Кодинг

<placeholder>

Верстка

<placeholder>

Рекоммендации по оформлению PSD-файлов

(draft-версия на скорую руку)

1. Файлы следует именовать согласно страницам, которые они репрезентируют.

Если файл репрезентирует группу страниц, или общий дизайн для многих страниц — название должно отражать это.

Рекомендуется именовать файлы в БЕМ-стиле:

{имя страницы}__{имя подстраницы или компонента}

В имени всегда следует использовать английский lowercase с - в качестве разделителя. Исключение — название сайта (если оно присутствует), которое может содержать заглавные буквы.

Примеры:

• index.psd
• catalog.psd
• catalog__product.psd
• catalog__category-card.psd
• other.psd (например, для общего дизайна других страниц)

Если в проекте используется один PSD-файл для всех страниц (то есть, страницы включаются или выключаются внутри самого PSD-файла) — такой файл рекомендуется именовать просто именем самого проекта

Что касается превью-файлов, то их также следует всегда ложить в папку, имя которой соответствует текущей семантической версии проекта или предоставляемого превью.

Например:

0.1.0
├── index.png
├── catalog.png
└── catalog__product.png

Если у PSD-файлов или превью есть вариации, их следует обозначать с помощью добавления модификатора в БЕМ-стиле:

{имя файла}--{модификация}

Это также касается и превью-файлов.

Модификатор также можно применять и ко всей версии, если все превью в ней меняются.

Примеры:

• index.psd
• index--blue.psd

0.1.0
├── catalog.png
└── catalog--blue.png

0.1.0--blue
├── index.png
└── catalog.png

2. Слои следует именовать согласно компонентам, которые они представляют

В названиях слоёв следует использовать английский.

Рекомендуется использовать в качестве разделителя - вместо пробела.

Для именования слоев следует использовать lowercase, в то время как названия самих компонентов (например, Header, Footer, Category-card) следует писать с большой буквы.

Название должно быть понятным и отражать суть слоя. Не рекомендуется использовать сокращения, которые могут быть очевидны только вам (например, lt или i-p).

При именовании слоёв также следует использовать БЕМ-принципы, однако указание всей структуры можно упустить при вложенности, в то время как размещенные на одном уровне компоненты всегда должны иметь в названии сущность, частью которой они являются. Такой подход позволяет с легкостью всегда быстро понять, частью чего является слой.

Для вариаций слоев следует использовать БЕМ-модификатор, отделяемый --

Например:

├── Header
|   ├── logo
|   |   ├── logo
|   |   ├── logo--red
|   |   ├── Company Name Text
|   |
|   └── logo--big
|        ├── logo
|        └── Company Name Text
|
├── Content
|   ├── button__icon
|   ├── button__text
|   ├── button__bg
|   └── ...
|
└── ...

Для большинства проектов базовая структура выглядит примерно так:

├── Header
├── Sidebar (если есть)
├── Content
├── Footer
└── bg

Content предпочтительней чем Body. Последний вариант соответствует html-тегу <body>, который в действительности не является контентной зоной.

3. Если у сайта есть верстка, и она хороша — лучше использовать идентичные CSS-классам названия для компонентов и страниц

К сожалению, не на всех проектах это возможно, но для самых новых, где используется современная верстка следует использовать одинаковые имена для компонентов и страниц как в PSD-файлах, так и в самой верстке.

Консолидация имен в PSD-файлах и верстке позволяет значительно сократить разрыв между дизайнерами и верстальщиками, и разговаривать на "одном языке".

4. Используйте модульные смарт-объекты

Это нечто новое, привнесенное с CC-версией Photoshop.

Если в макете используются повторяемые компоненты (например, Header, Footer, bg, category-card) — вынесете их в отдельный файл и помещайте в основной PSD-файл как смарт-объект с помощью File —> Place Linked.

Таким образом, в случае необходимости вам не нужно будет редактировать шапку или футер в каждом файле отдельно.

Для именования таких файлов используйте БЕМ-именование, описанное выше.

Немного более подробно: https://github.com/mobify/handbooks/tree/master/photoshop-handbook#modules--linked-smart-objects

4. Используйте цвета для глобальных групп компонентов

Рекомендуется использовать серый цвет групп для компонентов, которые повторяются а каждой странице (например, Header, Footer и bg), в то время как контентную зону выделять другим цветом.

Не рекомендуется красить разные внутренние компоненты одной страницы разными цветами. Лучше приберечь разные цвета для разных страниц (если в одном PSD-файле находятся все страницы)

4. Используйте группы для объединения слоев в компоненты и слои

Главное при этом помнить про золотую середину — слишком мелкие компоненты не всегда разумно объединять в группу.

Не рекомендуется объединять 1 слой в группу — лучше просто переименуйте сам слой.

Исключение — когда сама группа используется для создания особого оверлей-эффекта.

4. Располагайте слои и группы в том порядке, в котором они появляются на странице

При этом если компоненты размещены на одной линии — размещайте их в порядке слева-направо.

5. Используйте векторную графику там, где это возможно

Не везде и не всегда можно обойтись только векторной графикой, но там где это возможно — лучше использовать именно её. Photoshop CC предоставляет достаточно большой набор инструментов, чтобы комфортно работать хотя бы с базовой векторной графикой.

Такой подход позволяет значительно сократить размер PSD-файла, а также позволяет без потерь в случае необходимости масштабировать проект.

Простые примеры, где растр следует без раздумий заменить, которые может использовать даже новичок:

• Любые квадратные или прямоугольные элементы со сплошным цветом — легко заменяются с помощью Rectangle Tool
• Слои с солидным (сплошным) цветом — следует заменить с помощью Layer —> New Fill Layer —> Solid Color
• Иконки — если они доступны в векторе — вставляйте их в проект тоже в векторе

По возможности также рекомендуется использовать векторные маски, а не растровые.

Не забудьте включить в параметрах Shape опцию Align edges, иначе можете получить расплывчатые края.

6. Применяйте маски и эффекты для групп

Если вам нужно наложить одинаковую маску на 10 слоев — объедините их в группу, и примените маску к ней.

Тоже касается и случае, когда разумней использовать эффект на группе, чем на 10 слоях.

6. Используйте эффекты там, где это возможно

Не стоит повторять эффекты Photoshop-а с помощью наложения слоёв, если в этом нет реально необходимости.

Например, если нужно сделать тень под текстом — используйте эффект, а не подложку из идентичного цвета под ней.

Аргумент крайне прост — при наложении слоёв вы увеличиваете количество слоёв, которые нужно редактировать. Если захотите поменять, например, такой текст — вам придётся редактировать его в двух местах.

7. Если обойтись без наложения нескольких одинаковых слоёв невозможно — используйте для дублирования смарт-объекты

Превратите основной объект в смарт-объект и дублируйте его. В таком случае Вам нужно будет редактировать всего 1 основной объект.

8. Прежде чем превращать текст в растр — подумайте дважды, можно ли без этого обойтись

Серьезно.

Если нужны трансформации текстового слоя — превратите его в смарт-объект и делайте с ним что хотите.

9. Не используйте в текстовых слоях то, что не стоит там использовать

Отключите в параметрах параграфа hyphenate — в html нет переносов.

Не используйте ручные переносы на новую строку и табуляцию — используйте параметры параграфа для этого. Всегда.

Не используйте Letter Spacing (расстояние между буквами) отличное от 0 — перенести в html этот параметр практически невозможно, поскольку в html подобный параметр значительно отличается визуально.

10. Используйте вертикальный ритм

Это значительно облегчит работу и Вам, и верстальщику.

Коротко — следует установить для себя базовый размер шрифта — например, 14px.

От размера шрифта следует рассчитать высоту строки. Рекомендованная высота строки — 1.5 от размера шрифта.

То есть, для шрифта в 14px высота строки будет равна 21px.

Высота строки составляет основную сетку, по которой рекомендуется работать.

Таким образом, все компоненты рекомендуется размещать на расстоянии, равном высоте строки, или любым прямым дивизиям высоты строки (1\2, 1\4 высоты строки, x1.5, x2 высоты строки, и так далее).

Такой подход позволяет получить унифицированный ритм сайта, который очень удобно и просто верстать — у вас практически не будет неожиданных "магических цифр", поскольку заранее известно, что все отступы так или иначе являются математическими последовательностями от базовой высоты строки.

Базовую высоту строк также стоит задать текстовым слоям.

С заголовками и другими текстами, размер которых больше или меньше все несколько более сложно, но, как правило, в самом макете их проще отстроить просто по сетке (каждая ячейка которой равна базовой высоте строки). В верстке-же о вычислениях позаботится SASS-фреймворк.

Немного подробней: http://csswizardry.com/2012/02/pragmatic-practical-font-sizing-in-css/

9. Прикладывайте в PSD-файлу все ассеты, которые в нём используются

Если в проект импортируются какие-то особые компоненты (например, шрифты или векторные иконки) — они обязательно должны быть приложены к PSD-файлу в папке assets.

9. Используйте Color Swatch для создания палитры проекта

Хороший пример: https://github.com/mobify/handbooks/tree/master/photoshop-handbook#colour-swatches

Не забудьте сохранить Color Swatch в папку с ассетами.

Если у Вас есть доступ к переменным SASS с цветами — рекомендуется именовать цвета соответственно им.