Разработка AngularJS

Настройка окружения разработки
Запуск тестов
Правила написания кода
Руководство по составлению сообщений коммитов
Приемы написания документации

Настройка окружения разработки

Документация описывает процесс настройки вашего окружения разработки для сборки и тестирования AngularJS, а также объясняет основные механики использования git, node, yarn и grunt.

Установка зависимостей

Перед тем как начать сборку AngularJS, вам необходимо установить и настроить следующие зависимости на вашем компьютере:

Git: Руководство GitHub по установке Git является хорошим источником информации.
Node.js v8.x (LTS): Мы используем Node для генерации документации, запуска веб-сервера для разработки, выполнения тестов и создания распаковываемых файлов. В зависимости от вашей системы вы можете установить Node либо из исходников, либо как предварительно упакованное приложение.

Мы рекомендуем использовать nvm (или nvm-windows) для управления и установки Node.js, что позволяет легко менять версию Node.js для каждого проекта.
Yarn: Мы используем Yarn для установки наших модульных зависимостей Node.js (вместо использования npm). Подробные инструкции по установке.

yarn-install: https://yarnpkg.com/en/docs/install* Java: Мы минифицируем JavaScript с помощью Closure Tools, что требует наличия установленной Java (версия 7 или выше) в переменной среды PATH.

Grunt: Мы используем Grunt в качестве системы сборки. Мы используем его как локальную зависимость, но вы также можете установить командную строку Grunt глобально (yarn global add grunt-cli), что позволит вам пропустить префикс yarn для всех наших команд Grunt.

Создание форка AngularJS на Github

Чтобы внести свой вклад в код AngularJS, вам необходим аккаунт на Github, чтобы вы могли отправлять код в свой собственный форк AngularJS и открывать Pull Requests в GitHub Repository.

Чтобы создать аккаунт на Github, следуйте инструкциям здесь. После этого перейдите к созданию форка основного репозитория AngularJS.

Создание AngularJS

Чтобы создать AngularJS, вы клонируете репозиторий исходного кода и используете Grunt для генерации незакомпилированных и закомпилированных файлов AngularJS:

# Клонировать ваш репозиторий GitHub:
git clone https://github.com/<github username>/angular.js.git

# Перейти в директорию AngularJS:
cd angular.js

# Добавьте основной репозиторий AngularJS как удаленный репозиторий upstream к вашему репозиторию:
git remote add upstream "https://github.com/angular/angular.js.git"
```# Установите зависимости на JavaScript:
yarn install

# Соберите AngularJS:
yarn grunt package

Примечание: Если вы используете Windows, вам необходимо использовать повышённую командную строку (правый клик мышью, запустить от имени администратора). Это связано с тем, что yarn grunt package создаёт некоторые символьные ссылки.

Результат сборки находится в директории build. Она состоит из следующих файлов и директорий:

angular-<версия>.zip — Полная архивированная версия, содержащая все файлы сборки выпуска.
angular.js / angular.min.js — Основной и минифицированный скрипт AngularJS.
angular-*.js / angular-*.min.js — Все остальные модульные скрипты AngularJS.
docs/ — Директория, содержащая автономную версию документации (та же, что и доступна по адресу docs.angularjs.org).

Запуск локального сервера разработки

Для отладки кода, выполнения конечных точек тестирования и обслуживания документов часто полезно иметь локальный HTTP-сервер. Для этой цели был предоставлен локальный веб-сервер, основанный на Node.js.

Чтобы запустить веб-сервер, выполните:
```
yarn grunt webserver
```
Чтобы получить доступ к локальному серверу, введите следующий URL в свой веб-браузер:
```
http://localhost:8000/
```
По умолчанию он служит содержимым директории проекта AngularJS.
Чтобы получить доступ к локально обслуживаемой документации, посетите этот URL:
```
http://localhost:8000/build/docs/
```## <a name="tests">Выполнение тестов</a>
```

Выполнение набора юнит-тестов

Мы пишем юнит-тесты и тесты интеграции с помощью Jasmine и выполняем их с помощью Karma. Чтобы выполнить все тесты один раз в Chrome, выполните:

yarn grunt test:unit

Чтобы выполнить тесты в других браузерах, используйте флаг командной строки:

yarn grunt test:unit --browsers=Chrome,Firefox

Примечание: между браузерами не должно быть пробелов. Chrome, Firefox является НЕВАЛИДНЫМ. Если у вас есть аккаунт SauceLabs или BrowserStack, вы также можете запустить модульные тесты на этих сервисах через заранее определенные customLaunchers. Узнайте больше в файле конфигурации Karma для всех заранее настроенных браузеров.

Например, чтобы запустить полный набор модульных тестов на выбранных браузерах:

# BrowserStack
yarn grunt test:unit --browsers=BS_Chrome,BS_Firefox,BS_Safari,BS_IE_9,BS_IE_10,BS_IE_11,BS_EDGE,BS_iOS_10
# SauceLabs
yarn grunt test:unit --browsers=SL_Chrome,SL_Firefox,SL_Safari,SL_IE_9,SL_IE_10,SL_IE_11,SL_EDGE,SL_iOS_10

Выполнение этих команд требует настройки [Karma Browserstack][karma-browserstack] или [Karma-SauceLabs][karma-saucelabs] соответственно.

При разработке, однако, более продуктивно постоянно запускать модульные тесты каждый раз, когда меняются исходные или тестовые файлы. Чтобы выполнить тесты в этом режиме, выполните следующие шаги:

Для запуска сервера Karma, захвата браузера Chrome и запуска модульных тестов, выполните: ```shell yarn grunt autotest
Для захвата других браузеров откройте этот URL в нужном браузере (URL может различаться, если у вас несколько экземпляров Karma, читайте вывод консоли Karma для правильного URL):
```
http://localhost:9876/
```
Для повторного запуска тестов просто измените любой исходный или тестовый файл.

Чтобы узнать больше обо всех заранее настроенных задачах Grunt выполните:

yarn grunt --help

Запуск набора тестов end-to-end

Конечные тесты AngularJS выполняются с помощью Protractor. Просто выполните:

yarn grunt test:e2e

Это запустит веб-сервер и выполнит тесты в Google Chrome.

Правила программированияДля обеспечения согласованности во всем исходном коде, имейте в виду эти правила при работе:

Все новые функции или исправления ошибок обязательно должны быть протестированы с помощью одного или нескольких [тестовых спецификаций][unit-testing].
Все публичные методы API обязательно должны быть документированы с использованием ngdoc, расширенной версии jsdoc (мы добавили поддержку для markdown и шаблонизации через @ngdoc тег). Чтобы узнать, как мы документируем наши API, проверьте существующий исходный код и раздел о написании документации.

Исключениями являются случаи, указанные ниже; в остальном мы следуем правилам, содержащимся в [Google's JavaScript Style Guide][js-style-guide]:

Не используйте пространства имён: Вместо этого весь базовый код AngularJS следует обернуть в анонимное замыкание и явно экспортировать наш API вместо его скрытого использования.
Обертывайте все код на 100 символов.
Вместо сложных иерархий наследования мы предпочитаем простые объекты. Мы используем прототипное наследование только при крайней необходимости.
Мы любим функции и замыкания и предпочитаем их объектам всякий раз, когда это возможно.
Для написания более компактного кода, который лучше минифицируется, мы используем внутренние псевдонимы, которые отображаются на внешний API. Посмотрите наш текущий код, чтобы понять, что имеется в виду. * Мы не переходим в эмбриональное состояние с аннотациями типов для частных внутренних API, если они не используются повсеместно в AngularJS. Лучшим руководством является то, что делает больше смысла. ### Определенные темы#### Настройка провайдера

При добавлении конфигурации (опций) к [провайдерам][docs.provider] мы следуем специальному шаблону.

Для каждой опции добавьте метод method, который...
- работает как геттер и возвращает текущее значение при вызове без аргументов
- работает как сеттер и возвращает сам себя для цепочки вызовов при вызове с аргументами
- для булевых опций использует схему названий <option>Enabled([enabled])
Непростые опции (например, объекты) должны копироваться или свойства явно присваиваться новому объекту таким образом, чтобы конфигурация не могла меняться во время выполнения программы.

Для примера булевой конфигурации см. [$compileProvider#debugInfoEnabled][code.debugInfoEnabled].

Для примера объектной конфигурации см. [$location.html5Mode][code.html5Mode].

Вызов ошибок

Пользовательские ошибки следует выбрасывать с помощью функции ошибки [minErr][code.minErr], которая предоставляет идентификаторы ошибок, шаблоны сообщений об ошибках и добавляет ссылку на подробное описание ошибки.

Ошибка $compile:badrestrict является хорошим примером хорошо определённой minErr: [код][code.badrestrict] и [описание][docs.badrestrict].

Правила коммитов в GitУ нас есть очень строгие правила относительно того, как могут быть отформатированы сообщения коммитов в Git. Это приводит к более читаемым сообщениям, которые легко просматривать при просмотре истории проекта. Кроме того, мы используем сообщения коммитов для создания журнала изменений AngularJS.Формат сообщений коммитов можно добавить с использованием типичной рабочей процедуры Git или через использование волшебника командной строки (CLI Wizard) (Commitizen). Чтобы использовать волшебника, запустите `yarn run commit` в вашем терминале после записи ваших изменений в Git.

Формат сообщения коммита

Каждое сообщение коммита состоит из шапки, тела и подвала. Шапка имеет специальный формат, который включает тип, область и тему:

<type>(<scope>): <subject>
<Пустая строка>
<body>
<Пустая строка>
<footer>

Шапка обязательна, а область шапки — необязательна.

Любой строкой сообщения коммита не может быть длиннее Yöntem 100 символов! Это позволяет сообщению быть легче воспринимаемым на GitHub, а также в различных инструментах Git.

Откат

Если коммит отменяет предыдущий коммит, он должен начинаться со слова revert: , за которым следует шапка отмененного коммита. В теле должно быть указано: Это отменяет коммит <hash>., где hash — это SHA коммита, который был отменен.

Тип

Должен быть одним из следующих:* feat: Новая функциональность

fix: Исправление ошибки
docs: Изменение документации без изменения кода
style: Изменения, которые не влияют на смысл кода (отступы, форматирование, отсутствие точек с запятой и т.д.)
refactor: Изменение кода, которое ни исправляет ошибку, ни добавляет новую функцию
perf: Изменение кода, повышающее производительность
test: Добавление недостающих или корректировка существующих тестов
chore: Изменения в процессе сборки или вспомогательных инструментах и библиотеках, таких как генерация документации### Область Область может быть любым значением, указывающим место изменения коммита. Например, $location$, $browser$, $compile$, $rootScope$, ngHref, ngClick, ngView`, и т.д...

Вы можете использовать * когда изменение затрагивает более одного места.

Предмет

Предмет содержит краткое описание изменений:

используйте императивное настоящее время: "изменить", а не "изменил" или "изменяет"
не используйте заглавные буквы
не ставьте точки в конце

Описание

Как и в случае с предметом, используйте императивное настоящее время: "изменить", а не "изменил" или "изменяет". Описание должно содержать мотивацию для изменения и контрастировать это с предыдущим поведением.

Подвал

Подвал должен содержать информацию о разрушительных изменениях и также является местом для ссылки на GitHub-задачи, закрытые этим коммитом.

Разрушительные изменения должны начинаться словами BREAKING CHANGE: с пробела или двух пустых строк. Все остальное сообщение коммита используется для этого.

Подробное объяснение можно найти в этом [документе][commit-message-format].

Создание документации

Проект AngularJS использует форму jsdoc, называемую ngdoc, для всех его документов кода.

Это значит, что все документы хранятся непосредственно в исходном коде и поэтому остаются синхронизированными при его изменении.Также есть дополнительный контент (руководство разработчика, страницы ошибок, учебник, и прочие страницы), который живёт внутри репозитория AngularJS в виде файлов markdown.

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

Извлечение документации из исходного кода, её обработка и сборка выполняются с помощью инструмента генерации документации [Dgeni][dgeni].

[commit-message-format]: https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits### Локальная сборка и просмотр документации Документация может быть собрана с нуля с помощью Grunt:

yarn grunt docs

Это делегирует задачу сборки документов Gulp.

Обратите внимание, что приложение для документации использует локальные файлы сборки для запуска. Это означает, что вам может потребоваться сначала выполнить сборку:

yarn grunt build

(Это также необходимо, если вы вносите изменения в minErrors).

Чтобы просмотреть документацию, см. Запуск локального сервера разработки.

Написание JSDoc

Утилита ngdoc имеет базовую поддержку для многих стандартных директив JSDoc. Однако она особенно заинтересована в следующих блочных тегах:* @name имя — имя документа ngdoc

@param {тип} имя описание — описание параметра функции
@returns {тип} описание — описание того, что возвращает функция
@requires — обычно указывает, что требуется модуль JavaScript; в сервисе Angular используется для описания зависимостей от других сервисов
@property — описание свойства объекта
@description — используется для предоставления описания компонента в markdown
@link — указывает ссылку на URL или тип в справочнике API. Ссылки на API имеют следующую структуру: * пространство имён модуля, за которым следует . (необязательно, по умолчанию ng)
- тип @ngdoc (см. ниже), за которым следует : (необязательно, автоматически выводится)
- имя
- метод, свойство или анкер (необязательно)
- отображаемое имя
Например: {@link ng.module:$rootScope.Scope#$new Scope.$new()}.
@example — указывает пример. Это может быть просто блок кода или выполнимый пример.
@deprecated — указывает, что следующий код устарел и не должен использоваться. В документации AngularJS есть два конкретных шаблона, которые можно использовать для дальнейшего описания устаревания: sinceVersion="<версия>" и removeVersion="<версия>".

Тип в @param и @returns должен быть заключен в фигурные скобки {}, например {Object|Array}. Параметры могут быть сделаны необязательными либо путём добавления = к типу, например {Object=}, либо путём помещения [имени] в квадратные скобки. Значения по умолчанию возможны только со вторым синтаксисом путём добавления =<значение> к имени параметра, например @param {boolean} [ownPropsOnly=false]. Описание может содержать разметку в формате Markdown.

Уникальные директивы JSDoc для AngularJS

Кроме стандартных тегов JSDoc существуют специфичные для базы кода Angular:* @ngdoc — указывает тип документируемого объекта. Подробнее см. ниже.

@eventType emit|broadcast — указывает, является ли событие отправленным (emit) или широковещательным (broadcast).
@usage — показывает, как использовать функцию или директиву. Обычно автоматически генерируется.
@knownIssue — добавляет информацию о известных особенностях, проблемах или ограничениях API, а также возможных решениях. Эта секция предназначена не для отображения ошибок.Следующие директивы являются уникальными для директив:
@animations — указывает, какие анимации поддерживаются директивой.
@multiElement — указывает, может ли директива распространяться на несколько элементов.
@priority — указывает приоритет директивы.
@restrict — используется для отображения способа использования директивы. Например, для [E]lement, [A]ttribute и [C]lass используйте @restrict EAC.
@scope — указывает, что директива создаст новый скоуп.

Директива `@ngdoc`

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

overview — общая страница (руководство, индекс API).
provider — поставщик AngularJS, такой как $compileProvider или $httpProvider.
service — внедряемое сервисное средство AngularJS, такое как $compile или $http.
object — хорошо определённый объект (чаще всего представленный как сервис).
function — функция, доступная другим методам (например, вспомогательная функция внутри модуля ng).
method — метод на объекте/сервисе/контроллере.
property — свойство на объекте/сервисе/контроллере.
event — событие AngularJS, которое пропагируется через дерево $scope.
directive — директива AngularJS.
filter — фильтр AngularJS.
error — описание ошибки minErr.### Общее руководство с использованием Markdown

Любой текст в тегах может содержать разметку в формате Markdown. Обычно можно использовать любую функциональность Markdown.

Заголовки

Используйте только заголовки уровня h2 и ниже, так как заголовок страницы установлен в h1. Также убедитесь, что вы следуете иерархии заголовков. Это гарантирует правильное создание таблицы содержания.

Блоки кода

Код в одну строку можно указать, заключив его в обратные апострофы (\'). Блок многострочного кода можно заключить в тройные обратные апострофы (```), но лучше, если он будет заключён в теги <pre>...</pre> с отступами для каждой строки кода.

Написание исполняемых (живых) примеров и тестов end-to-end

Возможно встраивание примеров в документацию вместе с соответствующими тестами end-to-end. Эти примеры и сценарии будут преобразованы в исполняемые блоки кода внутри документации. Поэтому важно, чтобы они работали правильно. Для обеспечения этого все эти сценарии end-to-end выполняются как часть непрерывной интеграции.

Если вы добавляете пример с тестом end-to-end, вам следует выполнить тест локально сначала, чтобы убедиться, что он проходит. Вы можете заменить it(...) на fit(...) для выполнения только вашего теста, но убедитесь, что вернули его обратно к it(...) перед коммитом.#### Тег <example> Этот тег идентифицирует блок HTML, который определяет исполняемый пример. Он может принимать следующие атрибуты:

анимации — если установлено значение true, то этот пример использует ngAnimate.
зависимости — список дополнительных модулей Angular, разделённых точкой с запятой, которые должны быть загружены, например angular-animate.js.
название — каждый пример должен иметь название. Оно должно начинаться с имени компонента, например имя директивы, и не содержать пробелов.
модуль — имя приложения модуля, как определено в JavaScript примера.

Внутри этого тега мы предоставляем теги <file>, которые указывают, какие файлы содержат код примера.

<example
  module="angularAppModule"
  name="exampleName"
  deps="angular-animate.js;angular-route.js"
  animations="true">
  ...
  <file name="index.html">...</file>
  <file name="script.js">...</file>
  <file name="animations.css">...</file>
  <file name="protractor.js">...</file>
  ...
</example>
```Вы можете увидеть пример хорошо определённого примера [в документации `ngRepeat`][code.ngRepeat-example]. [Закрытие задач]: https://help.github.com/articles/closing-issues-via-commit-messages/
[Руководство по закрытию задач для изменений локализации]: https://github.com/google/closure-library/wiki/Internationalization-(i18n)-changes-in-Closure-Library
[code.badrestrict]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/ng/compile.js#L1107-L1110
[code.debugInfoEnabled]: https://github.com/angular/angular.js/blob/32fbb2e78f53d765fbb170f7cf99e42e072d363b/src/ng/compile.js#L1378-L1413
[code.html5Mode]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/ng/location.js#L752-L797
[code.minErr]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/minErr.js#L53-L113
[code.ngRepeat-example]: https://github.com/angular/angular.js/blob/0822d34b10ea0371c260c80a1486a4d508ea5a91/src/ng/directive/ngRepeat.js#L249-L340
[формат сообщений коммита]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
[Общая база данных локальных установок (CLDR)]: http://cldr.unicode.org
[корпоративное cla]: http://code.google.com/legal/corporate-cla-v1.0.html
[dgeni]: https://github.com/angular/dgeni
[docs.badrestrict]: docs/content/error/$compile/badrestrict.ngdoc
[docs.provider]: https://code.angularjs.org/snapshot/docs/api/auto/service/$provide#provider
[git-revert]: https://git-scm.com/docs/git-revert
[git-setup]: https://help.github.com/articles/set-up-git
[github-issues]: https://github.com/angular/angular.js/issues
[github]: https://github.com/angular/angular.js
[js-style-guide]: https://google.github.io/styleguide/javascriptguide.xml
[karma-browserstack]: https://github.com/karma-runner/karma-browserstack-launcher
[karma-saucelabs]: https://github.com/karma-runner/karma-sauce-launcher
[unit-testing]: https://docs.angularjs.org/guide/unit-testing
[yarn-install]: https://yarnpkg.com/en/docs/install

OSCHINA-MIRROR/mirrors-angularjs

Разработка AngularJS

Настройка окружения разработки

Установка зависимостей

Создание форка AngularJS на Github

Создание AngularJS

Запуск локального сервера разработки

Выполнение набора юнит-тестов

Запуск набора тестов end-to-end

Правила программированияДля обеспечения согласованности во всем исходном коде, имейте в виду эти правила при работе:

Вызов ошибок

Формат сообщения коммита

Откат

Тип

Предмет

Описание

Подвал

Создание документации

Написание JSDoc

Уникальные директивы JSDoc для AngularJS

Директива `@ngdoc`

Заголовки

Блоки кода

Написание исполняемых (живых) примеров и тестов end-to-end

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/mirrors-angularjs .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

Разработка AngularJS

Настройка окружения разработки

Установка зависимостей

Создание форка AngularJS на Github

Создание AngularJS

Запуск локального сервера разработки

Выполнение набора юнит-тестов

Запуск набора тестов end-to-end

Правила программированияДля обеспечения согласованности во всем исходном коде, имейте в виду эти правила при работе:

Вызов ошибок

Формат сообщения коммита

Откат

Тип

Предмет

Описание

Подвал

Создание документации

Написание JSDoc

Уникальные директивы JSDoc для AngularJS

Директива @ngdoc

Заголовки

Блоки кода

Написание исполняемых (живых) примеров и тестов end-to-end

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/mirrors-angularjs

Директива `@ngdoc`