Thanks for the interest in contributing to Ionic Framework!
Please see the Contributor Code of Conduct for information on the rules of conduct.
Creating an Issue
It is required to clearly describe the steps necessary to reproduce the issue that is being ran into. Although we would love to help users as much as possible, diagnosing issues without clear reproduction steps is extremely time-consuming and not sustainable.
The issue list of this repository is exclusively for bug reports and feature requests. Non-conforming issues will be closed immediately.
Issues with no clear steps to reproduce will not be triaged. If an issue is labeled with "needs reply" and receives no further replies from the author of the issue for more than 5 days, it will be closed.
Got a new bug or feature requests, please start by making sure it hasn't already been reported. Existing issues can be searched through to see if there is a similar one already reported. Include closed issues as it may have been closed with a solution.
Next, create a new issue that thoroughly explains the problem. Please fill out the populated issue form before submitting the issue.
Creating a Pull Request
Thanks for taking the time to contribute! Before submitting a pull request, we ask that an issue be created that explains the bug or feature request and states the plan on creating a pull request for it. If an issue already exists, please comment on that issue stating that a pull request is being worked on. This helps to keep track of the pull request and makes sure there isn't duplicated effort.
Looking for an issue to fix? Make sure to look through our issues with the help wanted label!
- Fork the repo.
- Clone the fork.
- Make a branch for the change.
npm install(make sure node and npm have been installed first)
- Make any changes to the component.
- Modify the e2e test in the
test/directory under the component directory, if possible. If the test does not exist and it is possible to show the change, please create a new test in a directory called
- If there is a
*.spec.tsfile located in the
test/folder, update it to include a karma test for your change, if needed. If this file doesn't exist, please notify us.
gulp testto make sure all tests are working, regardless if a test was added.
gulp lint.tsand fix any linter errors.
- If the css property is something that the user may want to override and it won't break the component layout, it should be given a Sass variable. See our doc on naming Sass variables.
- After any changes to the Sass files run the Sass Linter:
- Requires Ruby. Skip this step entirely if you are unable to install Ruby.
- Install the linter:
gem install scss_lint
- Make sure to run the linter at the root of the repository.
gulp lint.sassand fix any linter errors.
- Run the gulp e2e task to build all tests:
- Run the gulp e2e.watch task to watch a specific test (replace
buttonwith the component you are modifying and
basicwith the test folder):
gulp e2e.watch --f=button/basic
- A browser should open at
http://localhost:8080/dist/e2e. From here, navigate to the component being changed.
- If the changes look good, its time to commit!
- To add or modify API Documentation for a component, it should be added/changed in the
readme.mdfile in the component's directory. If the updates are to a specific
@Method, then please make the changes to the component's TypeScript (
*.ts). Properties, events and methods information within the
readme.mdfile are auto generated directly from the JSDoc comments within the TypeScript file.
- In order to run the API documentation locally, the
ionic-siterepo needs to be cloned as a sibling to the
ionicrepo and then ran: https://github.com/ionic-team/ionic-site#local-build
- Then, run
gulp docsin the
ionicrepo every time a change is made and the site will update.
- If the change affects the component documentation, create an issue on the
- Create or modify the demo in the
If it is new, link to the demo in the component's TypeScript (
*.ts) file (under
src/components) by adding a link to it in the documentation using
@demo, for example:
/** * @name Badge * * ... * * @demo /docs/v2/demos/src/badge/ **/
gulp watch.demosto watch for changes to the demo
- Navigate to
http://localhost:8000/dist/demos/and then to the component's demo to view it.
- If the change affects the component demos, create an issue on the
Commit Message Format
There are precise rules over how our git commit messages should be formatted. This leads to readable messages that are easy to follow when looking through the project history. We also use the git commit messages to generate our changelog.
Must be one of the following:
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
The scope can be anything specifying place of the commit change. For example
nav, etc. If multiple commits have been made for the same component, please keep the naming of this component consistent. For example, if a change is made to navigation and the first commit is
nav should continue to be used for any more commits related to navigation.
The subject contains succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- do not capitalize first letter
- do not place a period
.at the end
- entire length of the commit message must not go over 50 characters
- describe what the commit does, not what issue it relates to or fixes
- be brief, yet descriptive - we should have a good understanding of what the commit does by reading the subject
By contributing your code to the ionic-team/ionic GitHub Repository, you agree to license your contribution under the MIT license.