Contributing to Aurelia
We'd love for you to contribute to our source code and to make our projects even better than they are today! Here are the guidelines we'd like you to follow.
Got a Question or Problem?
If you have questions about how to use Aurelia, please direct these to Gitter, Discourse, or StackOverflow.
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. Or, even better, you can submit a Pull Request with a fix.
Please see the Submission Guidelines below.
Want a Feature?
You can request a new feature by submitting an issue. 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 via an RFC 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 as a Pull Request.
Check out building and testing Aurelia to get started with setting up the repo, building, testing and debugging.
Submitting an Issue
Before you submit your issue, search the archive. It may be that it was already addressed. 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. Please provide all the information requested in the issue template. This will increase the chances of your issue being dealt with quickly.
Submitting a Pull Request
Before you submit your pull request consider the following guidelines:
Search the appropriate GitHub Repository 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:
git checkout -b my-fix-branch master
Create your patch, including appropriate test cases.
Follow our code rules (see below).
Run the full test suite and ensure that all tests pass.
Commit your changes using a descriptive commit message that follows our commit message conventions (see below). Adherence to the commit message conventions is required because release notes are automatically generated from these messages.
git commit -a
Note: The optional commit
-acommand line option will automatically "add" and "rm" edited files.
Build your changes locally and ensure all the tests in
npm run test-chrome
Push your branch to GitHub:
git push origin my-fix-branch
In GitHub, send a Pull Request to the master branch.
If we suggest changes then:
Make the required updates.
Re-run the test suite to ensure tests are still passing.
Rebase your branch and force push to your GitHub Repository (this will update your Pull Request):
git rebase master -i git push -f
Note: The first time you submit a PR to a project under the Aurelia organization on GitHub, you will be prompted to sign the Contributor License Agreement (CLA). We cannot accept the PR without this (see below for details).
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:
git push origin --delete my-fix-branch
Check out the master branch:
git checkout master -f
Delete the local branch:
git branch -D my-fix-branch
Update your master with the latest upstream version:
git pull --ff upstream master
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.
- All public API methods must be documented. To see how we document our APIs, please check out the existing docs.
- Instead of complex inheritance hierarchies, we prefer simple objects.
- Ensure that your code passes the lint check.
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 change log.
Commit Message Format
Each commit message consists of a type (mandatory), a scope (optional) and a description (mandatory).
feat(custom-element): add the strict option to the @customElement decorator fix(metadata): do not throw when a function is passed into decorate chore(all): fix no-unused-vars violations ci: fix an issue with the e2e test job docs: make some adjustments to git commit guidelines
The description should preferably be less than 100 characters, but if a few more characters is needed for a more accurate description, adding
--no-verify after the
git commit command can be used to override the automated verification.
Please use one of the following:
Note: the semver bump is always at minimum "patch", so in practice, everything that is not "feat" will behave like "fix". We make the distinction, however, for the purpose of this document because it adds a clearer meaning to the idea of "affects the semver bump".
|Semver bump||Changelog header||Applicable to||Clarification|
|"feat"||minor||Features||Code that is published to npm||New capabilities / additions to public api|
|"fix"||patch||Bugfixes||Code that is published to npm||Bugfixes, directly or indirectly related to public api|
|"perf"||-||Performance improvements||Code that is published to npm||Performance improvements, directly or indirectly related to public api|
|"refactor"||-||Refactorings||Code that is published to npm||Improvements, directly or indirectly related to public api, that don't fit the description of any other type|
|"docs"||-||-||Code/content that may or may not be published to npm||Markdown documents, jsdoc comments|
|"style"||-||-||Code that may or may not be published to npm||Linting fixes in code|
|"test"||-||-||Code that is NOT published to npm||Code that tests code that is published to npm: additions/changes to unit, integration, e2e tests|
|"build"||-||-||Code/config that is NOT published to npm||Code or config that produces the artifacts that are published to npm|
|"ci"||-||-||Code/config that is NOT published to npm||Code or config that affects the CI/CD pipeline|
|"chore"||-||-||Anything that may or may not be published to npm||Any kind of house-keeping that does not clearly belong to any other type|
|"revert"||-||-||A specific commit that has been committed before and affects the changelog||Will cancel out the addition of said commit in the changelog (not yet implemented)|
For practical reasons, different degrees of strictness apply depending on the type of commit.
- The types "feat", "fix", "perf" and "refactor" MUST be used when they are applicable as per the description above, and not in any other case.
- The types "perf" and "refactor" MAY be used interchangeably if the changes in code have aspects of both these types (pick the intended or dominant type).
- Type types "feat" and "fix" MUST be used exclusively in isolation. If necessary, split up the changes into multiple commits to ensure that a single commit does not contain fixes as well as features, or multiple fixes / multiple features.
- In all other cases, when in doubt, "chore" MAY be used as a 'catch-all' type, because nothing else ends up in the change log, but for clarity of the commit history it is still preferable to be as precise as possible.
The scope could be anything specifying the package, file, or theme of the commit change. For example
Signing the CLA
Please sign our Contributor License Agreement (CLA) as part of the pull request process. You will see GitHub prompt you in the "checks" section of the PR after you have made your submission. For any code changes to be accepted, the CLA must be signed. It's a quick process, we promise! You can view the CLA in advance here.
Joining the Core Team
The Aurelia Core Team is made up of select community members who are committed to maintaining and evolving Aurelia over the long-term. The team may grow or shrink depending on project needs, member availability, and other factors. Core team members are typically long-time Aurelia community members who have shown enthusiasm while taking initiative to improve Aurelia in various ways, including fixing bugs, implementing features, writing documentation/books/blogs, triaging issues, and more. Each member has shown a consistency of quality and cadence in their contributions. If you are interested in joining the core team, please reach out to email@example.com. We'd be happy to discuss opportunities with you.