From fee98e6838574cd663a9eee1dee84ddff2c8842c Mon Sep 17 00:00:00 2001 From: Martin Staffa Date: Wed, 4 Oct 2017 22:43:35 +0200 Subject: [PATCH 1/3] docs(CONTRIBUTING): update and improve - remove outdated info - add info about writing docs from Wiki - add info about development setup from docs contribute.md - add info about running tests on Saucelabs / Browserstack TODO: - add link to contributing.md to Contribung page - add link to changelog.md to dropdown in docs -- link to current version changelog entry? Closes #7303 Closes #9444 --- CONTRIBUTING.md | 588 ++++++++++++++---- README.md | 20 - .../templates/app/indexPage.template.html | 1 + docs/content/misc/contribute.ngdoc | 175 +----- 4 files changed, 477 insertions(+), 307 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22849d948da2..8ef4eab85c74 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,80 +3,95 @@ We'd love for you to contribute to our source code and to make AngularJS even better than it is today! Here are the guidelines we'd like you to follow: - - [Code of Conduct](#coc) - - [Question or Problem?](#question) - - [Issues and Bugs](#issue) - - [Feature Requests](#feature) - - [Submission Guidelines](#submit) - - [Coding Rules](#rules) - - [Commit Message Guidelines](#commit) - - [Signing the CLA](#cla) - - [Further Info](#info) +- [Code of Conduct](#coc) +- [Questions, Bugs, Features](#requests) + - [Questions and Problems](#question) + - [Issues and Bugs](#issue) + - [Feature Requests](#feature) + - [Improving Documentation](#docs) + - [Issue Submission Guidelines](#submit) +- [Code & Documentation Contributions](#contributions) + - [Development Setup](#development-setup) + - [Coding Rules](#rules) + - [Writing Documentation](#writing-docs) + - [Commit Message Guidelines](#commit) + - [Pull Request Submission Guidelines](#submit-pr) + - [Signing the CLA](#cla) ## Code of Conduct Help us keep AngularJS open and inclusive. Please read and follow our [Code of Conduct][coc]. +## Questions, Bugs, Features + ## Got a Question or Problem? -If you have questions about how to use AngularJS, please direct these to the [Google Group][groups] -discussion list or [StackOverflow][stackoverflow]. We are also available on [IRC][irc] and -[Gitter][gitter]. +Do not open issues for general support questions as we want to keep GitHub issues for bug reports and feature requests. You've got much better chances of getting your question answered on dedicated support platforms, the best being [Stack Overflow][stackoverflow]: + +Stack Overflow is a much better place to ask questions since: + +- there are thousands of people willing to help on Stack Overflow +- questions and answers stay available for public viewing so your question / answer might help someone else +- Stack Overflow's voting system assures that the best answers are prominently visible. + +To save your and our time, we will systematically close all issues that are requests for general support and redirect people to the section you are reading right now. -## Found an Issue? +Other channels for support are: +- the [Google Group][groups] discussion list +- the [AngularJS IRC][irc] +- the [AngularJS Gitter][gitter] -If you find a bug in the source code or a mistake in the documentation, you can help us by -submitting an issue to our [GitHub Repository][github]. Even better you can submit a Pull Request -with a fix. +## Found an Issue or Bug? + +If you find a bug in the source code, you can help us by submitting an issue to our [GitHub Repository][github]. Even better you can submit a Pull Request with a fix. + +**Please see the [Submission Guidelines](#submit) below.** -**Localization Issues:** AngularJS uses the [Google Closure I18N library] to generate +**Special Note for Localization Issues:** AngularJS uses the [Google Closure I18N library] to generate its own I18N files (the ngLocale module). This means that any changes to these files would be lost the next time that we import the library. Since the Closure library i18n data is itself auto-generated from the data of the [Common Locale Data Repository (CLDR)] project, errors in the data should be reported there. See also the [Closure guide to i18n changes]. -**Please see the [Submission Guidelines](#submit) below.** - -## Want a Feature? +## Missing a Feature? -You can request a new feature by submitting an issue to our [GitHub Repository][github]. If you -would like to implement a new feature then consider what kind of change it is: +You can request a new feature by submitting an issue to our [GitHub Repository][github-issues]. -* **Major Changes** that you wish to contribute to the project should be discussed first on our - [dev mailing list][angular-dev] or [IRC][irc] so that we can better coordinate our efforts, - prevent duplication of work, and help you to craft the change so that it is successfully accepted - into the project. -* **Small Changes** can be crafted and submitted to the [GitHub Repository][github] as a Pull - Request. +If you would like to implement a new feature then consider what kind of change it is: +* **Major Changes** that you wish to contribute to the project should be discussed first in an + [GitHub issue][github-issues] that clearly outlines the changes and benefits of the feature. +* **Small Changes** can directly be crafted and submitted to the [GitHub Repository][github] + as a Pull Request. See the main section about [Documentation & Code Contributions](#code-contrib) + and specifically the [Pull Request Submission Guidelines](#submit-pr). ## Want a Doc Fix? +Should you have a suggestion for the documentation, you can open an issue and outline the problem +or improvement you have - however, creating the doc fix yourself is much better! + If you want to help improve the docs, it's a good idea to let others know what you're working on to minimize duplication of effort. Create a new issue (or comment on a related existing one) to let others know what you're working on. +If you're making a small change (typo, phrasing) don't worry about filing an issue first. Use the friendly blue "Improve this doc" button at the top right of the doc page to fork the repository +in-place and make a quick change on the fly. The commit message is preformatted to the right type and scope, so you only have to add the description. + For large fixes, please build and test the documentation before submitting the PR to be sure you haven't accidentally introduced any layout or formatting issues. You should also make sure that your -commit message starts with "docs" and follows the **[Commit Message Guidelines](#commit)** outlined -below. +commit message follows the **[Commit Message Guidelines](#commit)**. -If you're just making a small change, don't worry about filing an issue first. Use the friendly blue -"Improve this doc" button at the top right of the doc page to fork the repository in-place and make -a quick change on the fly. When naming the commit, it is advised to follow the commit message -guidelines below, by starting the commit message with **docs** and referencing the filename. Since -this is not obvious and some changes are made on the fly, this is not strictly necessary and we will -understand if this isn't done the first few times. - -## Submission Guidelines - -### Submitting an Issue +## Issue Submission Guidelines Before you submit your issue search the archive, maybe your question was already answered. If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize the effort we can spend fixing issues and adding new features, by not reporting duplicate issues. -Providing the following information will increase the chances of your issue being dealt with + +The "[new issue][github-new-issue]" form contains a number of prompts that you should fill out to +make it easier to understand and categorize the issue. + +In general, providing the following information will increase the chances of your issue being dealt with quickly: * **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps @@ -93,94 +108,183 @@ Here is a great example of a well defined issue: https://github.com/angular/angu **If you get help, help others. Good karma rulez!** -### Submitting a Pull Request -Before you submit your pull request consider the following guidelines: -* Search [GitHub](https://github.com/angular/angular.js/pulls) for an open or closed Pull Request - that relates to your submission. You don't want to duplicate effort. -* Please sign our [Contributor License Agreement (CLA)](#cla) before sending pull - requests. We cannot accept code without this. -* Make your changes in a new git branch: +## Code and Documentation Contributions - ```shell - git checkout -b my-fix-branch master - ``` +### Development Setup -* Create your patch, **including appropriate test cases**. -* Follow our [Coding Rules](#rules). -* Run the full AngularJS test suite, as described in the [developer documentation][dev-doc], - and ensure that all tests pass. -* Commit your changes using a descriptive commit message that follows our - [commit message conventions](#commit) and passes our commit message presubmit hook - (`validate-commit-msg.js`). Adherence to the [commit message conventions](#commit) is required, - because release notes are automatically generated from these messages. +This document describes how to set up your development environment to build and test AngularJS, and +explains the basic mechanics of using `git`, `node`, `yarn`, `grunt`, and `bower`. - ```shell - git commit -a - ``` - Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. +#### Installing Dependencies -* Build your changes locally to ensure all the tests pass: +Before you can build AngularJS, you must install and configure the following dependencies on your +machine: - ```shell - grunt test - ``` +* [Git](http://git-scm.com/): The [Github Guide to + Installing Git](https://help.github.com/articles/set-up-git) is a good source of information. -* Push your branch to GitHub: +* [Node.js v6.x (LTS)](http://nodejs.org): We use Node to generate the documentation, run a + development web server, run tests, and generate distributable files. Depending on your system, + you can install Node either from source or as a pre-packaged bundle. - ```shell - git push origin my-fix-branch - ``` + We recommend using [nvm](https://github.com/creationix/nvm) (or [nvm-windows](https://github.com/coreybutler/nvm-windows)) + to manage and install Node.js, which makes it easy to change the version of Node.js per project. + +* [Yarn](https://yarnpkg.com): We use Yarn to install our Node.js module dependencies (rather than using npm). + There are detailed installation instructions available at https://yarnpkg.com/en/docs/install. -In GitHub, send a pull request to `angular.js:master`. -If we suggest changes, then: +* [Java](http://www.java.com): We minify JavaScript using our + [Closure Tools](https://developers.google.com/closure/) jar. Make sure you have Java (version 7 or higher) + installed and included in your [PATH](http://docs.oracle.com/javase/tutorial/essential/environment/paths.html) + variable. -* Make the required updates. -* Re-run the AngularJS test suite to ensure tests are still passing. -* Commit your changes to your branch (e.g. `my-fix-branch`). -* Push the changes to your GitHub repository (this will update your Pull Request). +* [Grunt](http://gruntjs.com): We use Grunt as our build system. Install the grunt command-line tool globally with: -If the PR gets too outdated we may ask you to rebase and force push to update the PR: + ```shell + yarn global add grunt-cli + ``` + +#### Forking AngularJS on Github + +To contribute code to AngularJS, you must have a GitHub account so you can push code to your own +fork of AngularJS and open Pull Requests in the [GitHub Repository][github]. + +To create a Github account, follow the instructions [here](https://github.com/signup/free). +Afterwards, go ahead and [fork](http://help.github.com/forking) the [main AngularJS repository](https://github.com/angular/angular.js). + + +#### Building AngularJS + +To build AngularJS, you clone the source code repository and use Grunt to generate the non-minified and +minified AngularJS files: ```shell -git rebase master -i -git push origin my-fix-branch -f +# Clone your Github repository: +git clone https://github.com//angular.js.git + +# Go to the AngularJS directory: +cd angular.js + +# Add the main AngularJS repository as an upstream remote to your repository: +git remote add upstream "https://github.com/angular/angular.js.git" + +# Install node.js dependencies: +yarn install + +# Build AngularJS (which will install `bower` dependencies automatically): +grunt package ``` -_WARNING: Squashing or reverting commits and force-pushing thereafter may remove GitHub comments -on code that were previously made by you or others in your commits. Avoid any form of rebasing -unless necessary._ +**Note:** If you're using Windows, you must use an elevated command prompt (right click, run as +Administrator). This is because `grunt package` creates some symbolic links. -That's it! Thank you for your contribution! +**Note:** If you're using Linux, and `yarn install` fails with the message +'Please try running this command again as root/Administrator.', you may need to globally install `grunt` and `bower`: -#### After your pull request is merged +- sudo yarn global add grunt-cli +- sudo yarn global add bower -After your pull request is merged, you can safely delete your branch and pull the changes -from the main (upstream) repository: +The build output is in the `build` directory. It consists of the following files and +directories: -* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: +* `angular-.zip` — The complete zip file, containing all of the release build +artifacts. - ```shell - git push origin --delete my-fix-branch - ``` +* `angular.js` — The non-minified AngularJS script. -* Check out the master branch: +* `angular.min.js` — The minified AngularJS script. - ```shell - git checkout master -f - ``` +* `angular-scenario.js` — The (deprecated) AngularJS End2End test runner. -* Delete the local branch: +* `docs/` — A directory that contains a standalone version of the docs (same as served in `docs.angularjs.org`). - ```shell - git branch -D my-fix-branch - ``` +#### Running a Local Development Web Server -* Update your master with the latest upstream version: +To debug code, run end-to-end tests, and serve the docs, it is often useful to have a local HTTP server. For this purpose, we have made available a local web server based on Node.js. + +1. To start the web server, run: + ```shell + grunt webserver + ``` + +2. To access the local server, enter the following URL into your web browser: + ```text + http://localhost:8000/ + ``` + By default, it serves the contents of the AngularJS project directory. + +3. To access the locally served docs, visit this URL: + ```text + http://localhost:8000/build/docs/ + ``` + +#### Running the Unit Test Suite + +We write unit and integration tests with Jasmine and execute them with Karma. To run all of the +tests once on Chrome run: + +```shell +grunt test:unit +``` + +To run the tests on other browsers (Chrome, ChromeCanary, Firefox and Safari are pre-configured) use: + +```shell +grunt test:unit --browsers=Chrome,Firefox +``` + +**Note:** there should be _no spaces between browsers_. `Chrome, Firefox` is INVALID. + +If you have a Saucelabs or Browserstack account, you can also run the unit tests on these services via +our pre-defined customLaunchers. + +For example, to run the whole unit test suite: + +```shell +# Browserstack +grunt test:unit --browsers=BS_Chrome,BS_Firefox,BS_Safari,BS_IE_9,BS_IE_10,BS_IE_11,BS_EDGE,BS_iOS_8,BS_iOS_9,BS_iOS_10 +# Saucelabs +grunt test:unit --browsers=BS_Chrome,BS_Firefox,BS_Safari,BS_IE_9,BS_IE_10,BS_IE_11,BS_EDGE,BS_iOS_8,BS_iOS_9,BS_iOS_10 +``` + +Running these commands requires you to set up the [Karma Browserstack][karma-browserstack] or [Karma-Saucelabs][karma-saucelabs], respectively. + +During development, however, it's more productive to continuously run unit tests every time the source or test files change. To execute tests in this mode run: + +1. To start the Karma server, capture Chrome browser and run unit tests, run: + + ```shell + grunt autotest + ``` + +2. To capture more browsers, open this URL in the desired browser (URL might be different if you have multiple instance + of Karma running, read Karma's console output for the correct URL): + + ```text + http://localhost:9876/ + ``` + +3. To re-run tests just change any source or test file. + + +To learn more about all of the preconfigured Grunt tasks run: + +```shell +grunt --help +``` + + +#### Running the End-to-end Test Suite + +AngularJS's end to end tests are run with Protractor. Simply run: + +```shell +grunt test:e2e +``` + +This will start the webserver and run the tests on Chrome. - ```shell - git pull --ff upstream master - ``` ## Coding Rules @@ -188,8 +292,8 @@ To ensure consistency throughout the source code, keep these rules in mind as yo * All features or bug fixes **must be tested** by one or more [specs][unit-testing]. * All public API methods **must be documented** with ngdoc, an extended version of jsdoc (we added - support for markdown and templating via @ngdoc tag). To see how we document our APIs, please check - out the existing source code and see [this wiki page][ngDocs]. + support for markdown and templating via @ngdoc tag). To see how we document our APIs, please check out the existing source code and see the section about + [writing documentation](#writing-documentation) * With the exceptions listed below, we follow the rules contained in [Google's JavaScript Style Guide][js-style-guide]: * **Do not use namespaces**: Instead, wrap the entire AngularJS code base in an anonymous closure and @@ -203,6 +307,160 @@ To ensure consistency throughout the source code, keep these rules in mind as yo * We **don't go crazy with type annotations** for private internal APIs unless it's an internal API that is used throughout AngularJS. The best guidance is to do what makes the most sense. +### Specific topics + +#### Provider configuration + +When adding configuration (options) to [providers](https://code.angularjs.org/snapshot/docs/api/auto/service/$provide#provider), we follow a special pattern. + +- for each option, add a `method` that ... + - works as a getter and returns the current value when called without argument + - works as a setter and returns itself for chaining when called with argument + - for boolean options, uses the naming scheme `