1# Contributing to libphonenumber 2 3Thanks for contributing to libphonenumber! 4 5Please read the following before filing an issue or sending a pull request. 6 7We hope these guidelines will enhance your experience as a contributor to our 8library and know that we appreciate the time you put into making it better. 9 10## Checklist before filing an issue 11 12Please check the following: 13* Is the issue reproducible using the 14 [demo](http://libphonenumber.appspot.com/)? If not: 15 * Your issue may be resolved by upgrading to the latest version of the 16 library. (Reach out to the product/app team if you're not the developer!) 17 * If you are using a 18 [port](http://github.com/google/libphonenumber#third-party-ports), 19 issues should be reported against that project. 20 * If you are using the library through a front-end or wrapper, issues 21 should be reported against that project. 22* Has the issue already been discussed in the 23 [issues](http://issuetracker.google.com/issues/new?component=192347) or [discussion 24 group](https://groups.google.com/group/libphonenumber-discuss)? If so, you 25 may want to comment on an existing discussion. 26 27## Filing a metadata issue 28 29Please copy this template into your report and answer the questions to the best of your ability. 30For acceptable evidence, [see below](#provide-supporting-evidence). 31 32``` nomarkdown 33* Country: 34* Example number(s) and/or range(s): 35* Number type ("fixed-line", "mobile", "short code", etc.): 36* For short codes, cost and dialing restrictions: 37* Where or whom did you get the number(s) from: 38* Authoritative evidence (e.g. national numbering plan, operator announcement): 39* Link from demo (http://libphonenumber.appspot.com) showing error: 40``` 41 42As of March 2018, we kindly request that you use Google's [Issue Tracker](http://issuetracker.google.com/issues/new?component=192347) 43to report issues with the library. Using Issue Tracker will enable to us to 44get back to you more efficiently as we align GitHub user issues with ones 45reported at Google. Note that we transitioned active GitHub issues to Issue Tracker, 46but anything inactive for over a year must be filed again. To check if your issue 47was transitioned, see this [list of issues](https://issuetracker.google.com/hotlists/886952). 48 49Alternatively, if you have a particular issue with a Google product handling phone numbers (e.g. signup), 50you may also use the [Google Product Forums](https://productforums.google.com/forum). 51 52### Provide authoritative evidence 53 54Ideally, change requests for ranges should be accompanied by authoritative 55evidence such as official government or public carrier documents. 56 57If the evidence is publicly available online, please provide the link. 58 59If the evidence is not publicly available online, make sure that you have the 60rights to share this with us, and confirm this by reading and signing the 61appropriate Contributor License Agreement (CLA). Then we can accept this 62on GitHub, or we can invite you to a private Google Group archive if you 63prefer not to share on GitHub. 64 65See https://cla.developers.google.com/about to determine whether you need to 66sign a Corporate or Individual CLA. 67 68**By signing the CLA, you confirm that you have the rights to share the 69information with us, and that we may use, modify, reproduce, publicly display, 70and distribute the information in accordance with the library's [open source 71license](http://github.com/google/libphonenumber/blob/master/LICENSE).** 72 73* [Corporate CLA](http://developers.google.com/open-source/cla/corporate?csw=1): 74 * See https://cla.developers.google.com/about and follow the instructions. 75 * Once you are all set up, either create a validation issue for your 76 request, or go to the relevant open issue. 77 * Comment on the issue, using the email that's already set up for 78 your Corporate CLA, with "I signed the CLA." 79 * If you're set up correctly, someone from the team will update you on the 80 issue, with instructions for sending private documentation to our closed 81 mailing list. Only the core libphonenumber team has access to view 82 emails sent to this address. 83 84* [Individual CLA](http://cla.developers.google.com/about/google-individual?csw=1): 85 * See https://cla.developers.google.com/about to ensure that an Individual 86 CLA is what you need to sign, and for help with troubleshooting. 87 * When signing the Individual CLA, use the same email you used 88 (or will use) to file the corresponding issue, so that we may check 89 and you don't have to post your correct email in public. 90 * Once you are all set up, either create a validation issue for your 91 request, or go to the relevant open issue. 92 * If you're set up correctly, someone from the team will update you on the 93 issue, with instructions for sending private documentation to our closed 94 mailing list. Only the core libphonenumber team has access to view 95 emails sent to this address. 96 97## Pull requests 98 99Since all metadata (XML and mapping files) is generated automatically from other 100sources, we cannot accept pull requests to edit these files directly. This includes 101validation, formatting, geocoding, operator or timezone metadata. However this does 102not mean you cannot raise issues for this data. 103 104For changes specific to windows builds, see [Filing a code 105issue](#filing-a-code-issue) and make sure you have found a reviewer and tester 106before sending the pull request. If the issue wasn’t reproducible and seems to be 107specific to your build/setup, please prefer [creating a code bug](#filing-a-code-issue) or email the 108[discussion group](https://groups.google.com/group/libphonenumber-discuss) than creating a pull request. 109 110We are happy to review and accept pull requests for the following: 111 112* Bug fixes 113* Documentation and code hygiene cleanups 114 115This list is not exhaustive. To clarify whether we'd accept a pull request, and 116especially before spending significant time on one such as for a bug fix, we 117strongly encourage that you bring up the question on an issue. 118 119To get your pull request merged, we need the following: 120 121* A CLA signature. See the previous section. 122* If the email address you use in the Individual CLA is not already 123 associated with that GitHub account, [add it](https://help.github.com/articles/adding-an-email-address-to-your-github-account/). 124* If you need to modify an Individual CLA signature, such as to change the 125 GitHub username, go to https://cla.developers.google.com/clas and click 126 on "Edit Contact Information". 127* Responsiveness to back and forth review comments, because we will do a code 128 review. 129* A link to a clear description of what the pull request intends to solve in [Issue 130 Tracker](http://issuetracker.google.com/issues/new?component=192347). 131* Tests that illustrate the issue, if applicable. 132* Willingness and ability to implement the changes in C++, Java, and JS if 133 applicable. For example, changes to `PhoneNumberUtil.java` must be ported to 134 `phonenumberutil.cc` and `phonenumberutil.js`. 135 * The initial pull request may contain the implementation in only one 136 language to get approval on the approach. 137 138If this is not possible, please file an issue instead. 139 140## Filing a code issue 141 142When filing a code issue, include the specifics of your operating system and 143provide as much information as possible that helps us reproduce the problem. 144 145Please be advised that metadata updates are prioritized over code changes, 146except for bug fixes. In addition, we work with a limited number of build 147systems and may not be able to support every setup. 148 149In particular, we don't actively maintain windows builds but would be able to 150accept a PR provided someone else in the open-source community could test it out 151and would be able to help with the review. One way to look for such 152collaborators would be to email the [discussion 153group](https://groups.google.com/group/libphonenumber-discuss). Also see the 154[known Windows issues](FAQ.md#what-about-windows). 155