docs: update with concrete examples on how to use the library and var…

…ious readme updates (#238)

* docs: update with concrete examples on how to use the library

* docs: add contributing guide

.github/PULL_REQUEST_TEMPLATE/default_pull_request_template.md

@@ -0,0 +1,2 @@
+## Changes
+-

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to libphonenumber-csharp
+
+Thank you for considering contributing to libphonenumber-csharp! You can contribute to libphonenumber-csharp with issues and PRs.
+
+Simply filing issues for problems you encounter or contributing any implementation of an issue is greatly appreciated.
+
+### Suggested Workflow
+
+We use and recommend the following workflow:
+
+1. Create an issue for your work.
+    - You can skip this step for trivial changes.
+    - Reuse an existing issue on the topic, if there is one.
+    - For trivial changes, feel free to start work without an agreement from the maintainers.
+    - For slightly larger changes, you can reach out to the maintainers to discuss the change.
+    - Clearly state that you are going to take on implementing it if you are planning to, you can request that the issue be assigned to you.
+2. Create a personal fork of the repository on GitHub (if you don't already have one).
+3. In your fork, create a branch off of main (`git checkout -b mybranch`).
+    - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue.
+4. Make and commit your changes to your branch.
+5. Add new tests corresponding to your change, if applicable.
+6. Build the repository with your changes.
+    - Make sure that the builds are clean.
+    - Make sure that the tests are all passing, including your new tests.
+7. Create a pull request (PR) against the **main** branch.
+    - State in the description what issue or improvement your change is addressing.
+    - Check if all the Continuous Integration checks are passing.
+8. Wait for feedback or approval of your changes from the maintainers
+9. Maintainers will merge once all checks are green and they are happy with the change
+    - The next official build will automatically include your change.
+
+Essentially, we are following trunk based development

README.md

@@ -12,38 +12,124 @@ See [this](csharp/README.md) for details about the port.
 
 Phone number metadata is updated in the Google repo approximately every two weeks. This library is automatically updated by a [scheduled github action](https://github.com/twcclegg/libphonenumber-csharp/actions/workflows/create_new_release_on_new_metadata_update.yml) to include the latest metadata, usually within a day.
 
-## Example
+## Installation
 
-```cs
-  var phoneNumberUtil = PhoneNumbers.PhoneNumberUtil.GetInstance();
-  var e164PhoneNumber = "+44 117 496 0123";
-  var nationalPhoneNumber = "2024561111";
-  var smsShortNumber = "83835";
-  var phoneNumber = phoneNumberUtil.Parse(e164PhoneNumber, null);
-  phoneNumber = phoneNumberUtil.Parse(nationalPhoneNumber, "US");
-  phoneNumber = phoneNumberUtil.Parse(smsShortNumber, "US");
+Run the following command to add this library to your project
+
+```
+dotnet add package libphonenumber-csharp
+```
+
+Available on NuGet as package [`libphonenumber-csharp`](https://www.nuget.org/packages/libphonenumber-csharp).
+
+## Examples
+
+### Parsing a phone number
+```csharp
+using PhoneNumbers;
+
+var phoneNumberUtil = PhoneNumberUtil.GetInstance();
+var e164PhoneNumber = "+44 117 496 0123";
+var nationalPhoneNumber = "2024561111";
+var smsShortNumber = "83835";
+var phoneNumber = phoneNumberUtil.Parse(e164PhoneNumber, null);
+phoneNumber = phoneNumberUtil.Parse(nationalPhoneNumber, "US");
+phoneNumber = phoneNumberUtil.Parse(smsShortNumber, "US");
+```
+
+### Formatting a phone number
+```csharp
+using PhoneNumbers;
+
+var phoneNumberUtil = PhoneNumberUtil.GetInstance();
+var phoneNumber = phoneNumberUtil.Parse("+14156667777", "US");
+var formattedPhoneNumber = phoneNumberUtil.Format(phoneNumber, PhoneNumberFormat.INTERNATIONAL);
+var formattedPhoneNumberNational = phoneNumberUtil.Format(phoneNumber, PhoneNumberFormat.NATIONAL);
+
+Console.WriteLine(formattedPhoneNumber.ToString()); // +1 415-666-7777
+Console.WriteLine(formattedPhoneNumberNational.ToString()); // (415) 666-7777
+```
+
+### Check if a phone number is valid
+```csharp
+using PhoneNumbers;
+
+var phoneNumberUtil = PhoneNumberUtil.GetInstance();
+var phoneNumber = phoneNumberUtil.Parse("+14156667777", "US");
+var isValid = phoneNumberUtil.IsValidNumber(phoneNumber);
+
+Console.WriteLine(isValid); // true
+```
+
+### Get the type of a phone number
+```csharp
+using PhoneNumbers;
+
+var phoneNumberUtil = PhoneNumberUtil.GetInstance();
+var phoneNumber = phoneNumberUtil.Parse("+14156667777", "US");
+var numberType = phoneNumberUtil.GetNumberType(phoneNumber);
+
+Console.WriteLine(numberType); // PhoneNumberType.FIXED_LINE_OR_MOBILE
+```
+
+See [PhoneNumberType.cs](csharp/PhoneNumbers/PhoneNumberType.cs) for the various possible types of phone numbers
+
+### Get the region code for a phone number
+```csharp
+using PhoneNumbers;
+
+var phoneNumberUtil = PhoneNumberUtil.GetInstance();
+var phoneNumber = phoneNumberUtil.Parse("+14156667777", null);
+var regionCode = phoneNumberUtil.GetRegionCodeForNumber(phoneNumber);
+
+Console.WriteLine(regionCode); // US
 ```
 
 ## Features
 
-  * Parsing/formatting/validating phone numbers for all countries/regions of the world.
-  * GetNumberType - gets the type of the number based on the number itself; able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared Cost, VoIP and Personal Numbers (whenever feasible).
-  * IsNumberMatch - gets a confidence level on whether two numbers could be the same.
-  * GetExampleNumber/GetExampleNumberByType - provides valid example numbers for 218 countries/regions, with the option of specifying which type of example phone number is needed.
-  * IsPossibleNumber - quickly guessing whether a number is a possible phonenumber by using only the length information, much faster than a full validation.
-  * AsYouTypeFormatter - formats phone numbers on-the-fly when users enter each digit.
-  * FindNumbers - finds numbers in text input
+* Parsing/formatting/validating phone numbers for all countries/regions of the world.
+* GetNumberType - gets the type of the number based on the number itself; able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared Cost, VoIP and Personal Numbers (whenever feasible).
+* IsNumberMatch - gets a confidence level on whether two numbers could be the same.
+* GetExampleNumber/GetExampleNumberByType - provides valid example numbers for 218 countries/regions, with the option of specifying which type of example phone number is needed.
+* IsPossibleNumber - quickly guessing whether a number is a possible phone number by using only the length information, much faster than a full validation.
+* AsYouTypeFormatter - formats phone numbers on-the-fly when users enter each digit.
+* FindNumbers - finds numbers in text input
+
+See [PhoneNumberUtil.cs](csharp/PhoneNumbers/PhoneNumberUtil.cs) for the various methods and properties available.
 
 ## ToDo
 
-  * port read/write source xml data to binary for better performance and smaller .nupkg size (WIP)
-  * update / add / port new unit tests and logging from java source
+* port read / write source xml data to binary for better performance and smaller .nupkg size (WIP)
+* update / add / port new unit tests and logging from java source
 
 ## How to unfold automatic generated files
-  * Install Jetbrains - Resharper for Visual Studio
-  * File by file, right click and "Cleanup code"
-  * Check the unfolded file
 
-Available on NuGet as package [`libphonenumber-csharp`](https://www.nuget.org/packages/libphonenumber-csharp).
+* Install Jetbrains - Resharper for Visual Studio
+* File by file, right click and "Cleanup code"
+* Check the unfolded file
+
+## Running tests locally
+
+To run tests locally, you will need a zip version of the `geocoding.zip` file stored in the `resources` folder
+and `testgeocoding.zip` file stored in the `resources/test` folder.
+
+On linux, you can run the following commands to generate the zip accordingly
+
+```bash
+(cd resources/geocoding; zip -r ../../resources/geocoding.zip *)
+(cd resources/test/geocoding; zip -r ../../../resources/test/testgeocoding.zip *)
+```
+
+For windows, you can use the following powershell script
+
+```powershell
+Compress-Archive -Path "resources\geocoding\*" -DestinationPath "resources\geocoding.zip"
+Compress-Archive -Path "resources\test\geocoding\*" -DestinationPath "resources\test\testgeocoding.zip"
+```
+
+## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Donations
 
 [![Buy me a beer](https://raw.githubusercontent.com/twcclegg/libphonenumber-csharp/main/bmacButton.png)](https://www.buymeacoffee.com/tclegg)