Skip to content

Commit

Permalink
docs(readme,guides): add perf guide for IE. updates and corrections. (a…
Browse files Browse the repository at this point in the history 
…ngular#11262)

- refine the IE performance guide
- make the IE performance guide visible in the docs
- indicate 1.4.x as minimum version to line up with bower-material
- update branding in screenshot to AngularJS
- update PR and issue templates
- major updates to the Contributing guide for clarity and consistency
- remove text about the project being in early beta
- make it clear that we are not accepting major new feature requests
- clarify issue submission guidelines to use GitHub templates
- provide better examples of issue titles, commit messages, etc
- add details and clarity to the commit levels and team roles
- minor updates to the PR guide

Fixes angular#8616. Relates to angular#8658. Relates to angular#8329.
  • Loading branch information
@Splaktar @andrewseguin
Splaktar authored and andrewseguin committed Apr 27, 2018
1 parent f6bdc05 commit 777a7e1
Show file tree
Hide file tree
Showing 9 changed files with 333 additions and 241 deletions.
155 changes: 79 additions & 76 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,13 @@
- [Submission Guidelines](#submit)

## <a name="coc"></a> Code of Conduct
Help us keep AngularJS open and inclusive.

Please read and follow our
Please help us keep AngularJS Material open and inclusive by reading and following our
[Code of Conduct](https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md).

<br/>
We are care deeply about our inclusive community and diverse group of members. As part of this,
we do take time away from development to enforce this policy through interventions in heated
discussions, one on one discussions to explain the policy to violators, and bans for repeat
violators.

## <a name="question"></a> Have a Question, Problem, or Idea?

Expand All @@ -23,26 +24,28 @@ If you have questions or ideas regarding AngularJS Material, please direct these

Otherwise, do you:

- [Found a Bug ?](#bug)
- [Want a Feature ?](#feature)
- [Want to report a Bug?](#bug)
- [Want to request an Enhancement?](#feature)

#### <a name="bug"></a> 1. Found a Bug or Issue?
#### <a name="bug"></a> 1. Want to report a Bug or Issue?
If you find a bug in the source code or a mistake in the documentation, we recommend that you first
review the [Online Documentation](http://material.angularjs.org/).
review the latest `master` version of the [Online Documentation](https://material.angularjs.org/HEAD/)
and use one of the Demos to create a CodePen that reproduces the issue.

Otherwise you can help us improve by submitting an issue to our
[GitHub Repository](https://github.com/angular/material/issues/new). Even better you can submit a
**Pull Request** with a fix. Your custom changes can be crafted in a repository fork and submitted
If the issue can be reproduced in the latest `master` version, you can help us by submitting an issue
to our [GitHub Repository](https://github.com/angular/material/issues/new). After the issue is triaged
(labels are applied to it), we invite you to submit a **Pull Request** with a proposed fix.
Your custom changes can be crafted in a repository fork and submitted
to the [GitHub Repository](https://github.com/angular/material/compare) as a Pull Request.


> **Important: Please review the [Submission Guidelines](#submit) below, before contributing to the
project**.
**Important**: Please review the [Submission Guidelines](#submit) below, before contributing to the
project.

#### <a name="feature"></a> 2. Want a Feature?
You can request a new feature by
[submitting an issue](https://github.com/angular/material/issues/new). If you would like to
implement a new feature then consider what kind of change it is:
#### <a name="feature"></a> 2. Want to request an Enhancement?
You can request an enhancement by
[submitting an issue](https://github.com/angular/material/issues/new). After an issue is submitted,
if you would like to implement an enhancement then consider what kind of change it is:

* **Major Changes** that you wish to contribute to the project should be discussed first on our
[AngularJS Material Forum](https://groups.google.com/forum/#!forum/ngmaterial), so that we can better
Expand All @@ -52,81 +55,64 @@ implement a new feature then consider what kind of change it is:
[GitHub Repository](https://github.com/angular/material/compare) as a Pull Request.

## <a name="submit"></a> Issue Guidelines
Please note, this project is mature and stable with thousands of projects depending upon it.

Please note, this project is still in an early beta.

We're not actively reviewing unsolicited PRs from the community, although we welcome your feature
requests, doc corrections, and issue reports. If you're thinking of contributing code or docs to the
We welcome your enhancement requests, doc improvements, and issue reports.
However, we are not accepting major feature requests at this time.
If you're thinking of contributing code or documentation to the
project, please review [Submitting Pull Requests](#submitpr) before beginning any work.

#### Submitting an Issue
Before you submit your issue,
Before you submit an issue,
**[search](https://github.com/angular/material/issues?q=is%3Aissue+is%3Aopen)** the issues archive;
maybe your question was already answered. If your issue appears to be a bug, and hasn't been
reported, open a new issue.
maybe the issue has already been submitted or considered. If the issue appears to be a bug,
and hasn't been reported, open a [new issue](https://github.com/angular/material/issues/new).

> Do not report duplicate issues; help us maximize the effort we can spend fixing issues and
adding new features.
> Please **do not report duplicate issues**; help us maximize the effort we can spend fixing
issues and adding enhancements.

Providing the following information will increase the chances of your issue being dealt with
quickly:

* **Issue Title** - provide a concise issue title prefixed with a lower camelCase name of the
associated target or component (if any): `<component>: <issue title>`.
* **Issue Title** - provide a concise issue title prefixed with a snake-case name of the
associated service or component (if any): `<component>: <issue title>`.
Adding the `md-` prefix should be avoided.

> e.g.
> * mdSideNav: Adding swipe functionality [#35](https://github.com/angular/material/issues/35)
> * mdTextFloat: does not set required/ng-required
[#847](https://github.com/angular/material/issues/847)

* **Overview of the Issue** - if an error is being thrown, a non-minified stack trace helps.

* **AngularJS Material Version** - check the header of your `angular-material.js` file to determine
your specific version #.

```js
/*!
* AngularJS Material Design
* https://github.com/angular/material
* @license MIT
* v0.6.0-rc1-master-57f10f7
*/
```
* **Browsers and Operating System** - is this a problem with all browsers or only IE?
* **Reproduce the Error** - provide a live example (using [CodePen](http://codepen.io/),
[Plunker](http://plnkr.co/), [JSFiddle](http://jsfiddle.net/)).
* **Related Issues** - has a similar issue been reported before?
> * menu-bar: does not support dark mode themes [#11238](https://github.com/angular/material/issues/11238)
> * tooltip: memory leak on destroy [#11133](https://github.com/angular/material/issues/11133)
* **Complete the full Issue Template** - GitHub now supports issue templates and AngularJS Material
provides one to make submitting an issue with all of the required information more straightforward.

* **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).<br/><br/>
Here are two examples of well-defined issues:
- https://github.com/angular/material/issues/629
- https://github.com/angular/material/issues/277
causing the problem (line of code or commit).

#### <a name="submitpr"></a>Submitting Pull Requests

**Important**: With the exception of minor bugs and doc fixes, we are not actively reviewing
unsolicited PRs to AngularJS Material.
**Important**: We are not accepting major feature requests or PRs that contain major new features
or breaking changes at this time.

Please check with us via [the discussion forum](https://groups.google.com/forum/#!forum/ngmaterial)
before investing significant effort in a planned Pull Request submission; it's likely that we are already
working on a related PR.
before investing significant effort in a planned Pull Request submission; it's possible that we are
already working on a related PR or have decided that the enhancement does not belong in the core
AngularJS Material project.

* All contributions must be consistent with the AngularJS Material coding conventions. See the
[Coding Guidelines](../docs/guides/CODING.md)
* Submit proposed changes or additions as GitHub pull requests. See the
[Pull Request Guidelines](../docs/guides/PULL_REQUESTS.md)
* All contributions must be consistent with the AngularJS Material [Coding Conventions](../docs/guides/CODING.md).
* Submit proposed changes or additions as GitHub pull requests that follow the
[Pull Request Guidelines](../docs/guides/PULL_REQUESTS.md).

<br/>

## <a name="commit"></a> 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**. It is
important to note that we use the git commit messages to **generate** the AngularJS Material
[Changelog](../../CHANGELOG.md) document.
readable messages** that are easy to follow when looking through the **project history**.

> A detailed explanation of guidelines and conventions can be found in this
[document](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#).
It is important to note that we use the git commit messages to **generate** the AngularJS Material
[CHANGELOG](../../CHANGELOG.md) document. Improperly formatted commit messages may result in your
change not appearing in the CHANGELOG of the next release.

### <a name="commit-message-format"></a> Commit Message Format
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
Expand All @@ -141,7 +127,7 @@ format that includes a **type**, a **scope** and a **subject**:
```

> Any line of the commit message cannot be longer 100 characters!<br/>
This allows the message to be easier to read on github as well as in various git tools.
This allows the message to be easier to read on GitHub as well as in various Git tools.

##### Type
Must be one of the following:
Expand All @@ -158,10 +144,14 @@ Must be one of the following:
generation

##### Scope
The scope could be anything specifying the place of the commit change.
The scope could be anything that helps specifying the scope (or feature) that is changing.

Examples
- select(multiple):
- dialog(alert):

##### Subject
The subject contains succinct description of the change:
The subject contains a succinct description of the change:

* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize first letter
Expand All @@ -173,14 +163,29 @@ The body should include the motivation for the change and contrast this with pre

##### Footer
The footer should contain any information about **Breaking Changes** and is also the place to
reference GitHub issues that this commit **Closes**.
reference GitHub issues that this commit **Closes**, **Fixes**, or **Relates to**.

> Breaking Changes are intended to highlight (in the ChangeLog) changes that will require community
users to modify their code with this commit.
> Breaking Changes are intended to be highlighted in the ChangeLog as changes that will require
community users to modify their code after updating to a version that contains this commit.

<br/>
##### Sample Commit messages:
```text
fix(autocomplete): don't show the menu panel when readonly
##### Sample Commit message:
this could sometimes happen when no value was selected
Fixes #11231
```
```text
feat(chips): trigger ng-change on chip addition/removal
* add test of `ng-change` for `md-chips`
* add docs regarding `ng-change` for `md-chips` and `md-contact-chips`
* add demo for ng-change on `md-chips`
* add demo for ng-change on `md-contact-chips`
Fixes #11161 Fixes #3857
```

```text
refactor(content): prefix mdContent scroll- attributes
Expand Down Expand Up @@ -210,8 +215,6 @@ details on how to implement and submit your fixes, changes, or enhancements to A
This guideline provides details on creating a repository Fork of the AngularJS Material repository
and how to submit Pull Requests.



<br/>

## <a name="cla"></a> Signing the CLA
Expand Down
29 changes: 21 additions & 8 deletions .github/ISSUE_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,37 @@
### Bug, feature request, or proposal:
<!--
Filling out this template is required! Do not delete it when submitting your issue! Without this information, your issue may be auto-closed.
Please submit questions to the [AngularJS Material Forum](https://groups.google.com/forum/#!forum/ngmaterial) instead of submitting an issue.
-->
## Bug, enhancement request, or proposal:

<!-- Please note that we are not accepting major feature requests, i.e. requests for new components, at this time. -->

# CodePen and steps to reproduce the issue:
#### [CodePen Demo](http://codepen.io/team/AngularMaterial/pen/bEGJdd) which demonstrates the issue:


#### Detailed Reproduction Steps:
1.
1.

### What is the expected behavior?


### What is the current behavior?


## CodePen and steps to reproduce the issue:
##### [CodePen Demo](http://codepen.io/team/AngularMaterial/pen/bEGJdd) which shows your issue:
##### Detailed Reproduction Steps:

### What is the use-case or motivation for changing an existing behavior?


### Which versions of AngularJS, Material, OS, and browsers are affected?



- AngularJS:
- AngularJS Material:
- OS:
- Browsers:

### Is there anything else we should know? Stack Traces, Screenshots, etc.


<!-- Filling out this template is required. Without this information, your issue may be auto-closed. -->
<!-- Please double check that you have provided the required reproduction steps and a Demo via CodePen, Plunker, or GitHub repo. -->
17 changes: 8 additions & 9 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,30 @@
<!--
Filling out this template is required! Do not delete it when submitting a Pull Request! Without this information, your Pull Request may be auto-closed.
-->
## PR Checklist
Please check that your PR fulfills the following requirements:

- [ ] The commit message follows [our guidelines](https://github.com/angular/material/blob/master/.github/CONTRIBUTING.md#-commit-message-format)
- [ ] Tests for the changes have been added (for bug fixes / features)
- [ ] Docs have been added / updated (for bug fixes / features)

- [ ] Tests for the changes have been added or this is not a bug fix / enhancement
- [ ] Docs have been added, updated, or were not required

## PR Type
What kind of change does this PR introduce?

<!-- Please check the one that applies to this PR using "x". -->
```
[ ] Bugfix
[ ] Feature
[ ] Enhancement
[ ] Documentation content changes
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Documentation content changes
[ ] Infrastructure changes
[ ] Other... Please describe:
```

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying and link to a relevant issue. -->

<!-- Please describe the current behavior that you are modifying and link to one or more relevant issues. -->
Issue Number:


Expand All @@ -36,7 +36,6 @@ Issue Number:
[ ] Yes
[ ] No
```

<!-- If this PR contains a breaking change, please describe the impact and migration path for existing applications below. -->
<!-- Note that breaking changes are highly unlikely to get merged to master unless the validation is clear and the use case is critical. -->

Expand Down
18 changes: 9 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,15 @@ Quick Links:
* [Installing](#installing)


Please note that using AngularJS Material requires the use of **[AngularJS](https://angularjs.org/) 1.3.x** or higher.
Please note that using AngularJS Material requires the use of **[AngularJS](https://angularjs.org/) 1.4.x** or higher.
AngularJS Material is targeted for the browser versions shown below in the green boxes:

![ngm1_browser_support](https://user-images.githubusercontent.com/3506071/35176284-1419c42c-fd46-11e7-9381-d93e5c5db39a.png)

## <a name="demos"></a> Online Documentation and Demos

<div style="border: 1px solid #ccc">
<img src="https://user-images.githubusercontent.com/3506071/35176652-81464d34-fd48-11e7-81d3-ac58d7d10a32.png" alt="AngularJS Material docs website" style="display:block;">
<img src="https://user-images.githubusercontent.com/3506071/39335179-ef92562e-497f-11e8-9f27-e23dc3a868f9.png" alt="AngularJS Material docs website" style="display:block;">
</div><br>

- Visit [material.angularjs.org](https://material.angularjs.org/) online to review the API, see the
Expand Down Expand Up @@ -151,8 +151,8 @@ when using online tools such as [CodePen](http://codepen.io/), [Plunkr](http://p
```html
<head>

<!-- AngularJS Material CSS now available via Google CDN; version 1.1.6 used here -->
<link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/angular_material/1.1.6/angular-material.min.css">
<!-- AngularJS Material CSS now available via Google CDN; version 1.1.9 used here -->
<link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/angular_material/1.1.9/angular-material.min.css">

</head>
<body>
Expand All @@ -164,7 +164,7 @@ when using online tools such as [CodePen](http://codepen.io/), [Plunkr](http://p
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.7/angular-messages.min.js"></script>

<!-- AngularJS Material Javascript now available via Google CDN; version 1.1.4 used here -->
<script src="https://ajax.googleapis.com/ajax/libs/angular_material/1.1.6/angular-material.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angular_material/1.1.9/angular-material.min.js"></script>
</body>
```

Expand All @@ -182,10 +182,10 @@ pull directly from the distribution GitHub
<body>

<!-- AngularJS Material Dependencies -->
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.7/angular.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.7/angular-animate.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.7/angular-aria.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.7/angular-messages.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.9/angular.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.9/angular-animate.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.9/angular-aria.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.9/angular-messages.min.js"></script>

<!-- AngularJS Material Javascript using GitCDN to load directly from `bower-material/master` -->
<script src="https://cdn.gitcdn.link/cdn/angular/bower-material/master/angular-material.js"></script>
Expand Down
Loading

0 comments on commit 777a7e1

Please sign in to comment.