diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..165c6f8997 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,233 @@ +# Contributing to Angular 2 + +We would love for you to contribute to Angular 2 and help make it even better than it is +today! As a contributor, here are the guidelines we would 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) + +## Code of Conduct +Help us keep Angular open and inclusive. Please read and follow our [Code of Conduct][coc]. + +## Got a Question or Problem? + +If you have questions about how to *use* Angular, please direct them to the [Google Group][angular-group] +discussion list or [StackOverflow][stackoverflow]. We are also available on [Gitter][gitter]. + +## Found an Issue? +If you find a bug in the source code or a mistake in the documentation, you can help us by +[submitting an issue](#submit-issue) to our [GitHub Repository][github]. Even better, you can +[submit a Pull Request](#submit-pr) with a fix. + +## Want a Feature? +You can *request* a new feature by [submitting an issue](#submit-issue) to our [GitHub +Repository][github]. If you would like to *implement* a new feature then consider what kind of +change it is: + +* For a **Major Feature**, first open an issue and outline your proposal so that it can be +discussed. This will also allow us to 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 Features** can be crafted and directly [submitted as a Pull Request](#submit-pr). + +## Want a Doc Fix? +If you want to help improve the docs, then consider what kind of improvement it is: + +* For **Major Changes**, it's a good idea to let others know what you're working on to +minimize duplication of effort. Before starting, check out the issue queue for +issues labeled [#docs](https://github.com/angular/angular/labels/%23docs). +Comment on an issue to let others know what you're working on, or [create a new issue](#submit-issue) +if your work doesn't fit within the scope of any of the existing doc issues. +Please build and test the documentation before [submitting the Pull Request](#submit-pr), to be sure +you haven't accidentally introduced any layout or formatting issues. Also ensure that your commit +message is labeled "docs" and follows the [Commit Message Guidelines](#commit) given below. +* For **Small Changes**, there is no need to file an issue first. Simply [submit a Pull Request](#submit-pr). + +## Submission Guidelines + +### Submitting an Issue +Before you submit an 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 quickly: + +* **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps +* **Motivation for or Use Case** - explain why this is a bug for you +* **Angular Version(s)** - is it a regression? +* **Browsers and Operating System** - is this a problem with all browsers? +* **Reproduce the Error** - provide a live example (using [Plunker][plunker], + [JSFiddle][jsfiddle] or [Runnable][runnable]) or a unambiguous set of steps. +* **Related Issues** - has a similar issue been reported before? +* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be + causing the problem (line of code or commit) + +### Submitting a Pull Request (PR) +Before you submit your Pull Request (PR) consider the following guidelines: + +* Search [GitHub](https://github.com/angular/angular.dart/pulls) for an open or closed PR + that relates to your submission. You don't want to duplicate effort. +* Please sign our [Contributor License Agreement (CLA)](#cla) before sending PRs. + We cannot accept code without this. +* Make your changes in a new git branch: + + ```shell + git checkout -b my-fix-branch master + ``` + +* Create your patch, **including appropriate test cases**. +* Follow our [Coding Rules](#rules). +* Run the full Angular 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). Adherence to these conventions + is necessary because release notes are automatically generated from these messages. + + ```shell + git commit -a + ``` + Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files. + +* Push your branch to GitHub: + + ```shell + git push origin my-fix-branch + ``` + +* In GitHub, send a pull request to `angular:master`. +* If we suggest changes then: + * Make the required updates. + * Re-run the Angular 2 test suites for JS and Dart to ensure tests are still passing. + * Rebase your branch and force push to your GitHub repository (this will update your Pull Request): + + ```shell + git rebase master -i + git push -f + ``` + +That's it! Thank you for your contribution! + +#### After your pull request is merged + +After your pull request is merged, you can safely delete your branch and pull the changes +from the main (upstream) repository: + +* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: + + ```shell + git push origin --delete my-fix-branch + ``` + +* Check out the master branch: + + ```shell + git checkout master -f + ``` + +* Delete the local branch: + + ```shell + git branch -D my-fix-branch + ``` + +* Update your master with the latest upstream version: + + ```shell + git pull --ff upstream master + ``` + +## Coding Rules +To ensure consistency throughout the source code, keep these rules in mind as you are working: + +* All features or bug fixes **must be tested** by one or more specs (unit-tests). +* All public API methods **must be documented**. (Details TBC). +* With the exceptions listed below, we follow the rules contained in + [Google's JavaScript Style Guide][js-style-guide]: + * Wrap all code at **100 characters**. + +## Commit Message Guidelines + +We have very precise rules over how our git commit messages can be formatted. This leads to **more +readable messages** that are easy to follow when looking through the **project history**. But also, +we use the git commit messages to **generate the Angular change log**. + +### Commit Message Format +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special +format that includes a **type**, a **scope** and a **subject**: + +``` +(): + + + +