By submitting a pull request to this project, you agree to release your contribution under this project's license terms.
Before contributing, please review the Code of Conduct.
Contributing is easy! You can contribute either by raising compatibility issues with a website, researching and documenting what the right data for a quirk might be, and/or submitting a pull request to add a quirk. You can raise an issue at the repository's issues page. If you've done some investigation into a service's behavior, you can document it on an existing issue for that problem. If you'd like to submit a pull request, there are some additional special considerations for each type of quirk, detailed below.
When adding a data item to a top-level JSON object, please keep keys alphabetized. This assists with scanning the lists and with merging them.
One more point to consider is to keep your pull requests small and limited in scope to a specific change. (For example, it's best to submit a "Password Rule" for a single website or group of related websites in one pull request and not conflate unrelated changes that can prevent other from being merged.)
Contributing a password rule is appropriate if a service doesn't accept a password generated by your password manager with its default settings or with a reasonable configuration. Contributing a rule involves writing a rule, testing it, documenting your investigation, and submitting a pull request.
To create a password rule, you'll want to gather as much information as you can about what the website considers to be an acceptable password. You can learn this by reading any pre-stated requirements or error messages you see while experimenting with the website. Sometimes, websites don't do a great job of saying what their rules are, or their stated rules are inaccurate, and you have to determine their actual rules experimentally.
Once you understand the website's requirements, like minimum length, maximum length, sets of required characters, and allowed characters, you're ready to write a rule. The Password Rules Validation Tool is a great tool for writing and validating password rules.
The Password Rules Validation Tool will output example passwords generated with the current rule, as well as allow you to download large sets of example passwords. You can copy and paste or manually type these passwords into the website to see if your rule creates compatible passwords. You should try to test a few different generated passwords to better ensure that you got it right.
Once you've tested passwords generated by your rule, you'll edit quirks/password-rules.json and add a new website key mapping to a JSON object of information. The rule you'll want to copy out of the Password Rules Validation Tools is the "Rules formatted for UIKit", because it's a pure Rule without any HTML markup.
When you submit a pull request to add or update a Password Rule, you should include as much information about the website’s requirements as you were able to gather. Text printed on the website, or error messages, are great. If the rules were determined experimentally, information about what you tried is helpful, too. Adding screenshots of error messages can be useful.
When contributing or amending a set of websites sharing a credential backend, you should state why you believe the relevant domains do or do not share a credential backend, with evidence to support your claim. This may involve WHOIS information or content served from the domains themselves.
Use the website in question until you find the standalone page for updating the user's password, or a high-level "Account Information" or "Security" page. The closer the URL takes the user to be able to change their password, the better. Before adding a URL, ensure that it works properly both when the user is logged in and when they are not. URLs added to quirks/change-password-URLs.json should have a scheme of https unless the website does not allow changing the password on an https page.
When contributing or amending a set of websites that require that the user append a generated code to their password when signing in, you should state why you believe the relevant domains require such. This may involve citing a URL to the relevant support page for the website.
If you have a new type of quirk or another resource, that you feel that other password managers could use to improve users' experiences and make password management more attractive for people who aren't using a password manager, please reach out to this project's maintainers at Apple so we can discuss the details.
If you are a representative from a website on the list, and you’ve incorporated the rule into your website or make it unnecessary, you can request a rule for your website to be removed. You can do this by filing an issue with the repository's issue tracker, or by submitting a pull request with a change. You may be asked to prove your affiliation with the service in question.