2020-04-17 22:15:58 +03:00
# Contribution Guidelines for Firefox Accounts
2014-02-27 22:37:15 +04:00
2020-04-17 22:15:58 +03:00
Anyone is welcome to help with Firefox Accounts, but it's important to
recognize that Firefox Accounts is a complex tool written by Mozilla and used
2020-05-19 20:56:04 +03:00
solely within Mozilla or by parties tightly coupled to Mozilla. The team's
2020-04-17 22:15:58 +03:00
goal is focused on serving Mozilla's requirements -- not being easy to set up
or easily usable in other scenarios.
In order to scale effectively, we may use technologies which have significant
barriers to entry (eg. cost or expertise).
If you're filing bugs, working on documentation, or helping reproduce a
problem, thank you for your help and please read below for guidelines.
If you want to write code, and you are not an experienced programmer you will
probably be more successful [looking for other projects at
2020-05-19 20:56:04 +03:00
Mozilla](https://whatcanidoformozilla.org) to contribute to. The Firefox
2020-04-17 22:15:58 +03:00
Accounts team is happy to support open source contributions but we have limited
time to assist in getting the FxA codebase up and running on other platforms.
We use the standard `help wanted` and `good first issue` labels on GitHub to
help identify bugs for contributors to work on.
To get in touch with us and other community members:
2014-08-19 01:45:27 +04:00
2020-02-28 21:14:52 +03:00
- Matrix: [#fxa:mozilla.org ](https://chat.mozilla.org/#/room/#fxa:mozilla.org )
2014-08-19 01:45:27 +04:00
- Mailing list: < https: // mail . mozilla . org / listinfo / dev-fxacct >
2019-04-22 15:14:02 +03:00
- and of course, [the issues list ](https://github.com/mozilla/fxa/issues )
2020-02-28 21:14:52 +03:00
UPDATE: On March 2020, Mozilla moved from IRC to Matrix. For more information on Matrix, check out the following wiki article: < https: / / wiki . mozilla . org / Matrix > .
2019-04-22 15:14:02 +03:00
## Code of Conduct
You must agree to abide by the [Mozilla Community Participation Guidelines ](https://www.mozilla.org/about/governance/policies/participation/ )
2014-08-19 01:45:27 +04:00
2019-10-23 19:35:37 +03:00
## Bug Reports
2014-08-19 01:45:27 +04:00
2019-04-22 15:14:02 +03:00
You can [file issues on GitHub ](https://github.com/mozilla/fxa/issues/new ). Please try to include as much information as you can and under what conditions
2014-08-19 01:45:27 +04:00
you saw the issue.
2020-04-17 22:15:58 +03:00
## Development Process
2019-10-23 19:35:37 +03:00
2022-08-20 00:57:33 +03:00
[Read about our development process ](https://mozilla.github.io/ecosystem-platform/reference/team-processes/development-process )
2019-10-23 19:35:37 +03:00
## Sending Pull Requests
2014-08-19 01:45:27 +04:00
Patches should be submitted as pull requests (PR).
Before submitting a PR:
2019-10-23 19:35:37 +03:00
2020-04-17 22:15:58 +03:00
- Your code must run and pass all the automated tests before you submit your PR for review. "Work in progress" pull requests are allowed to be submitted, but should be opened as a `draft` and should not be merged until all tests pass and the code has been reviewed.
2014-08-19 01:45:27 +04:00
- Your patch should include new tests that cover your changes. It is your and your reviewer's responsibility to ensure your patch includes adequate tests.
2019-04-22 15:14:02 +03:00
- Your patch must be [GPG signed ](https://help.github.com/articles/managing-commit-signature-verification ) to ensure the commits come from a trusted source.
2014-08-19 01:45:27 +04:00
When submitting a PR:
2019-10-23 19:35:37 +03:00
2020-04-17 22:15:58 +03:00
- You agree to and have the legal right to license your code under the project's [license ](/LICENSE ).
2020-06-18 04:13:10 +03:00
- Base your branch off the current `main` .
2014-08-19 01:45:27 +04:00
- Add both your code and new tests if relevant.
2015-06-15 04:31:40 +03:00
- Run `grunt lint` and `npm test` to make sure your code passes linting and tests.
2014-08-19 01:45:27 +04:00
- Please do not include merge commits in pull requests; include only commits with the new relevant code.
2016-01-21 14:26:36 +03:00
- Your commit message must follow the
2020-06-18 04:13:10 +03:00
[commit guidelines ](https://github.com/mozilla/fxa/blob/main/CONTRIBUTING.md#git-commit-guidelines ).
2020-06-12 00:36:23 +03:00
- To skip CI tests add the "🙈 skip ci" github label to the PR.
- You can skip only specific packages by also adding the corresponding "fxa-" label, for example "fxa-content-server".
2022-08-20 00:57:33 +03:00
- Be aware that a member of the FxA team will need to open a separate PR for CI
to run properly.
2014-08-19 01:45:27 +04:00
See the main [README.md ](/README.md ) for information on prerequisites, installing, running and testing.
2019-10-23 19:35:37 +03:00
## Code Review
2014-08-19 01:45:27 +04:00
2019-04-22 15:14:02 +03:00
This project is production Mozilla code and subject to our [engineering practices and quality standards ](https://developer.mozilla.org/docs/Mozilla/Developer_guide/Committing_Rules_and_Responsibilities ). Every patch must be peer reviewed. This project is part of the [Firefox Accounts module ](https://wiki.mozilla.org/Modules/Other#Firefox_Accounts ), and your patch must be reviewed by one of the listed module owners or peers.
2014-08-19 01:45:27 +04:00
2014-05-15 22:54:33 +04:00
## Git Commit Guidelines
2021-09-30 22:46:00 +03:00
We loosely follow the [Angular commit guidelines ](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#type ) of `<type>(<scope>): <subject>` where `type` must be one of:
2014-05-15 22:54:33 +04:00
2019-10-23 19:35:37 +03:00
- **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
2014-05-15 22:54:33 +04:00
semi-colons, etc)
2019-10-23 19:35:37 +03:00
- **refactor**: A code change that neither fixes a bug or 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
2014-05-15 22:54:33 +04:00
generation
2014-06-18 02:40:39 +04:00
### Scope
2019-10-23 19:35:37 +03:00
2014-06-18 02:40:39 +04:00
The scope could be anything specifying place of the commit change. For example `oauth` ,
`fxa-client` , `signup` , `l10n` etc...
### Subject
2019-10-23 19:35:37 +03:00
2014-06-18 02:40:39 +04:00
The subject contains succinct description of the change:
2019-10-23 19:35:37 +03:00
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize first letter
- no dot (.) at the end
2014-06-18 02:40:39 +04:00
2016-12-13 19:49:32 +03:00
### Body
2019-10-23 19:35:37 +03:00
2020-05-19 20:56:04 +03:00
The body should describe the purpose of the commit, so that it's clear why this change is being
made. To assist in writing this along with the footer, a git commit template (saved as `~/.gitmessage` )
can be used:
```text
feat: SUBJECT LINE
Because:
*
This commit:
2015-07-28 23:19:17 +03:00
2020-05-19 20:56:04 +03:00
*
Closes #
```
2021-09-30 22:46:00 +03:00
After creating `~/.gitmessage` , update git to use the template with the following:
```
git config --global commit.template ~/.gitmessage
```
A text editor will open with the template any time `git commit` is run without the `-m` flag.
2020-05-19 20:56:04 +03:00
Just as in the **subject** , use the imperative, present tense: "change" not "changed" nor "changes". Commits
are expected to follow this format.
2014-06-18 02:40:39 +04:00
2019-04-22 15:14:02 +03:00
### Footer
2019-10-23 19:35:37 +03:00
2014-06-18 02:40:39 +04:00
The footer should contain any information about **Breaking Changes** and is also the place to
2020-05-19 20:56:04 +03:00
reference GitHub issues that this commit **Closes** . In order to maintain a reference to the context of the commit, add
`fixes #<issue_number>` if it closes a related issue or `issue #<issue_number>`
if it's a partial fix.
2014-06-18 02:40:39 +04:00
2021-04-08 18:12:02 +03:00
## How to keep your fork in sync with the latest changes?
Once your PR is merged, it's recommended to pull new changes from `main` (which will also include the one that you made).
So for that purpose, specify a new remote `upstream` which will be pointing to the actual [mozilla/fxa ](https://github.com/mozilla/fxa ) repo.
```sh
git remote add upstream https://github.com/mozilla/fxa.git
```
To sync your local copy of the fork with the `upstream` changes, run the following commands:
```sh
git fetch upstream
git checkout main
git merge upstream/main
```
Great, now the local copy of the repo is up-to-date. But your fork on Github won’ t be updated until you push to it, so go ahead and run:
```sh
git push origin main
```
For more info, see [Github Help: Syncing a Fork ](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork ).
2014-02-27 22:37:15 +04:00
## Servers
- **stage** - https://accounts.stage.mozaws.net/
- **production** - https://accounts.firefox.com/
2014-11-23 02:47:32 +03:00
## Dependencies and Tools
2014-06-20 01:23:05 +04:00
2022-08-20 00:57:33 +03:00
### yarn
2014-11-23 02:47:32 +03:00
2022-08-20 00:57:33 +03:00
We use [yarn ](https://yarnpkg.com/ ) to manage dependencies. Required components are [automatically
2020-06-18 04:13:10 +03:00
installed](https://github.com/mozilla/fxa/blob/main/package.json#L6) when you install this project.
2014-11-23 02:47:32 +03:00
2016-12-13 19:49:32 +03:00
### L10N
2020-04-17 22:15:58 +03:00
To contribute translations visit [Pontoon ](https://pontoon.mozilla.org/ ).
2014-02-27 22:37:15 +04:00
2020-04-17 22:15:58 +03:00
Use the `FXA_L10N_SHA` to pin L10N files to certain Git SHA. If not set then the `master` branch SHA will be used.