From a1c9a416394174668b61468ea20b6e527e57c4a5 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Mon, 28 Oct 2013 22:48:47 +0000 Subject: docs(CONTRIBUTING.md): add more info for contributors Closes #4636 --- CONTRIBUTING.md | 162 +++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 142 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ed029ff1..f4853e88 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,41 +1,163 @@ -## Submitting issues +#Contributing to AngularJS -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]. +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: -## Guidelines +## 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]. + +## Found an Issue? +If you find a bug in the source code or a mistake in the documentation, you can help us by +submitting and issue to our [GitHub Repository][github]. Even better you can submit a Pull Request +with a fix. + +***Localization Issue:*** *Angular.js uses the [Google Closure I18N library], to generate its own I18N files. This means that +any changes to these files would be lost the next time that we import the library. The recommended +approach is to submit a patch to the I18N project directly, instead of submitting it here.* + +**Please see the Submission Guidelines below**. + +## Want 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: + +* **Major Changes** that you wish to contribute to the project should be discussed first on our +[mailing list][groups] 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 [GitHub Repository][github] as a Pull Request. + +## Submission Guidelines + +### Submitting an Issue +Before you submit your issue follow the following guidelines: * Search the archive first, it's likely that your question was already answered. -* A live example demonstrating your problem or question, will get an answer faster. -* Create one using this [template][template] +* A live example demonstrating the issue, will get an answer faster. +* Create one using [Plunker][plunker] or [JSFiddle][jsfiddle]. * If you get help, help others. Good karma rulez! 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. -## Contributing to Source Code +### Submitting a Pull Request +Before you submit your pull request follow the following guidelines: + +* Search GitHub for an open or closed Pull Request that relates to your submission. You don't want + to duplicate effort. +* Make your changes in a new git branch +* Follow our Coding Rules +* Follow our Git Commit Guidelines +* Build your changes locally and on Travis (by pushing to GitHub) to ensure all the tests pass. +* Sign the Contributor License Agreement (CLA). We cannot accept code without this. +* If we suggest changes then you can modify your branch, rebase and force a new push to your GitHub + repository to update the Pull Request. + +## 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-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 ngdocs and see [this wiki page][ngDocs]. +* 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 angular code base in an anonymous closure and + export our API explicitly rather than implicitly. + * Wrap all code at **100 characters**. + * Instead of complex inheritance hierarchies, we **prefer simple objects**. We use prototypical + inheritance only when absolutely necessary. + * We **love functions and closures** and, whenever possible, prefer them over objects. + * To write concise code that can be better minified, we **use aliases internally** that map to the + external API. See our existing code to see what we mean. + * 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. + +## Git Commit 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 AngularJS change log**. -We'd love for you to contribute to our source code and to make AngularJS even -better than it is today! +### 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**: -Please read the [contribution guidelines][contribute] to learn about how to submit code -as well as other useful info like how to build and test AngularJS code. +``` +(): + + + +