fxa/CONTRIBUTING.md

Contribution Guidelines for Firefox Accounts

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 solely within Mozilla or by parties tightly coupled to Mozilla. The team's 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 Mozilla to contribute to. The Firefox 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:

• Matrix: #fxa:mozilla.org
• Mailing list: https://mail.mozilla.org/listinfo/dev-fxacct
• and of course, the issues list

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.

Code of Conduct

You must agree to abide by the Mozilla Community Participation Guidelines

Bug Reports

You can file issues on GitHub. Please try to include as much information as you can and under what conditions you saw the issue.

Development Process

Read about our development process

Sending Pull Requests

Patches should be submitted as pull requests (PR).

Before submitting a PR:

• 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.
• 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.
• Your patch must be GPG signed to ensure the commits come from a trusted source.

When submitting a PR:

• You agree to and have the legal right to license your code under the project's license.
• Base your branch off the current main.
• Add both your code and new tests if relevant.
• Run grunt lint and npm test to make sure your code passes linting and tests.
• Please do not include merge commits in pull requests; include only commits with the new relevant code.
• Your commit message must follow the commit guidelines.
• 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".
• Be aware that a member of the FxA team will need to open a separate PR for CI to run properly.

See the main README.md for information on prerequisites, installing, running and testing.

Code Review

This project is production Mozilla code and subject to our engineering practices and quality standards. Every patch must be peer reviewed. This project is part of the Firefox Accounts module, and your patch must be reviewed by one of the listed module owners or peers.

Git Commit Guidelines

We loosely follow the Angular commit guidelines of <type>(<scope>): <subject> where type must be one of:

• 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 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 generation

Scope

The scope could be anything specifying place of the commit change. For example oauth, fxa-client, signup, l10n etc...

Subject

The subject contains succinct description of the change:

• use the imperative, present tense: "change" not "changed" nor "changes"
• don't capitalize first letter
• no dot (.) at the end

Body

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:

feat: SUBJECT LINE
Because:

*

This commit:

*

Closes #

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.

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". Commits are expected to follow this format.

Footer

The footer should contain any information about Breaking Changes and is also the place to 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.

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 repo.

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:

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:

git push origin main

For more info, see Github Help: Syncing a Fork.

Servers

• stage - https://accounts.stage.mozaws.net/
• production - https://accounts.firefox.com/

Dependencies and Tools

yarn

We use yarn to manage dependencies. Required components are automatically installed when you install this project.

L10N

To contribute translations visit Pontoon.

Use the FXA_L10N_SHA to pin L10N files to certain Git SHA. If not set then the master branch SHA will be used.