Skip to content

Latest commit

 

History

History
118 lines (103 loc) · 7.71 KB

requirements.md

File metadata and controls

118 lines (103 loc) · 7.71 KB

Требования к оформлению вопросов

  • При формулировке вопроса предпочтение отдавать именно вопросительной форме, а не утвердительной (типа "рассказать про..."): 
      // менее предпочтительно
  Рассказать про hover в мобильных браузерах.

  // более предпочтительно
  Как работает hover в мобильных браузерах?
  • Объединять вопросы по смыслу
    • Вопросы можно вкладывать в объединяющие названия тем: 
      * Ветки
  * Что такое ветка?
  * Зачем нужны ветки?
  ...
      или в объединяющие вопросы: 
      * Как задать количество и размеры строк (колонок)?
  * Какие можно использовать единицы для того, чтобы задать размеры строк (колонок)?
  * Как задать несколько строк (колонок) одинакового размера?
  ...
    • Также допустимо писать вопросы по одной теме на одной строке, если вопросов не сильно много и они не сильно длинные. Вопросы в таком случае следует писать в отдельных предложениях, а не в одном: 
      // плохо
* Что такое кросс-доменные iframes и какие они имеют ограничения?

// хорошо
* Что такое кросс-доменные iframes? Какие они имеют ограничения?
  • Каждый вопрос представляет собой одно или несколько предложений. Соответственно, он должен начинаться с большой буквы и иметь знак препинания в конце.
    • Объединяющие темы не являются вопросами и оформляются без знаков препинания: 
        * Шрифты
    * Как и в каких единицах можно задавать размер шрифта?
    * В каких форматах можно задавать цвет шрифта?
    ...
    • Перечисляющие списки в рамках одного вопроса оформляются без знаков препинания: 
        * Рассказать про атрибуты `<form>`:
    * `action`
    * `autocomplete`
    ...
  • Конструкции из кода (названия CSS свойств, JavaScript методов, HTML тегов и так далее) должны заключаться в косые кавычки: 
    * Что такое `padding`?

* Можно ли прервать обход элементов в методе `forEach`?
  • Для подсветки синтаксиса в примерах кода должен быть указан язык: 
      ```js
    const a = 5;

Требования к оформлению ресурсов

  • Для ресурсов должна быть выделена отдельная часть документа с соответствующим заголовком.
  • В одном документе может быть один или несколько разделов с ресурсами. Если в документе расмотрено множество тем, то предпочтительнее располагать ресурсы для каждой темы отдельно друг от друга.
  • Размер заголовка ресурсов должен отличаться на 2 порядка от размера ближайшего заголовка темы: 
    # Тема
### Ресурсы

## Тема
#### Ресурсы

### Тема
##### Ресурсы
  • Названия ресурсов
    • Названия ресурсов должны отражать смысл содержащейся в них информации. Указывать сайт в названии ресурса избыточно: URL можно посмотреть, наведя на ссылку в браузере.
    • Названия ресурсов не могут содержать ни каких знаков препинания на конце, кроме ? и !.
    • Названия ресурсов должны по возможности браться из заголовков: заголовков статей, вопросов (например, на stackoverflow), видео, страниц и так далее: 
      * [Immediately-Invoked Function Expression (IIFE)](http://benalman.com/news/2010/11/immediately-invoked-function-expression/)

* [How does Array.prototype.slice.call() work?](https://stackoverflow.com/questions/7056925/how-does-array-prototype-slice-call-work)

* [Attlassian Git Tutorial](https://www.atlassian.com/git)

* [toPrimitive abstract operation](https://www.ecma-international.org/ecma-262/9.0/index.html#sec-toprimitive)
    • При этом не всегда стоит тащить весь заголовок в название ресурса: иногда из него достаточно взять только какую-то часть (например, как сделано в примере ресурса по гиту). Иногда наоборот: заголовка может быть недостаточно для описания ресурса, и в таком случае необходимо описать ресурс самому (например, как сделано в примере ресурса по toPrimitive).
    • Книги указываются следующим образом: [Название книги] ([Автор], [Глава/Раздел и т.д.]):
    Чистый код. Создание, анализ, рефакторинг (Роберт Мартин, глава 9 "Модульные тесты")
  • В качестве ресурса в первую очередь должен выступать оригинал, а не перевод. Если необходимо добавить ссылку на перевод, то он "вкладывается" в ссылку на оригинал под названием "Перевод": 
    * [You Don't Know JS: Async & Performance. Chapter 4: Generators](https://github.com/getify/You-Dont-Know-JS/blob/master/async%20%26%20performance/ch4.md)
  * [Перевод](https://github.com/devSchacht/You-Dont-Know-JS/blob/master/async%20%26%20performance/ch4.md)
    • При этом, если название ресурса взято дословно из оригинала, то оно должно быть написано точно так же, т.е. не надо менять регистр букв, добавлять какие-то знаки препинания и так далее: 
      // плохо
You don't know js: async and performance

// хорошо
You Don't Know JS: Async & Performance

Требования к оформлению pull request (PR)

  • Заголовки PR должны именоваться по следующему шаблону: 
    уровень/топик: содержание PR
    например: 
    mid2/network: add transport protocols