diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b8842471..b2455e71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,20 +4,22 @@ The Open Location Code project strongly encourages technical contributions. We hope you'll become an ongoing participant in our open source community, but we also welcome one-off contributions for the issues you're particularly passionate about. -- [Filing issues](#filing-issues) - * [Bugs](#bugs) - * [Suggestions](#suggestions) -- [Contributing code](#contributing-code) -- [Contributing a new implementation](#contributing-a-new-implementation) -- [Contributor License Agreement](#contributor-license-agreement) -- [Ongoing participation](#ongoing-participation) - * [Discussion channels](#discussion-channels) +- [Contributing to Open Location Code](#contributing-to-open-location-code) + - [Filing issues](#filing-issues) + - [Bugs](#bugs) + - [Suggestions](#suggestions) + - [Contributing code](#contributing-code) + - [Contributing a new implementation](#contributing-a-new-implementation) + - [Contributor License Agreement](#contributor-license-agreement) + - [Ongoing participation](#ongoing-participation) + - [Discussion channels](#discussion-channels) ## Filing issues ### Bugs -If you find a bug in an Open Location Code library, please [file an issue](https://github.com/google/open-location-code/issues/new). Members of the community are regularly monitoring issues and will try to fix open bugs quickly. +If you find a bug in an Open Location Code library, please [file an issue](https://github.com/google/open-location-code/issues/new). +Members of the community are regularly monitoring issues and will try to fix open bugs quickly. The best bug reports provide a detailed description of the issue, step-by-step instructions for predictably reproducing the issue, and possibly even a working example that demonstrates the issue. @@ -26,7 +28,8 @@ instead of filing an issue here. ### Suggestions -The Open Location Code project is meant to evolve with feedback. The project and its users appreciate your thoughts on ways to improve the design or features or creative ways to use the codes. +The Open Location Code project is meant to evolve with feedback. +The project and its users appreciate your thoughts on ways to improve the design or features or creative ways to use the codes. To make a suggestion [file an issue](https://github.com/google/open-location-code/issues/new). @@ -41,26 +44,31 @@ The Open Location Code project accepts and greatly appreciates code contribution A few things to note: * The Open Location Code project follows the [fork & pull](https://help.github.com/articles/using-pull-requests/#fork--pull) model for accepting contributions. -* We follow [Google's JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html). More generally make sure to follow the same comment and coding style as the rest of the project. -* Do not try to address multiple issues in a single pull request. In some cases, you might even resolve a single issue with multiple PRs (e.g. if you are changing multiple implementations). -* Include [tests](TESTING.md) when contributing code. There are tests that you can use as examples. +* We follow [Google's JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html). + More generally make sure to follow the same comment and coding style as the rest of the project. +* Do not try to address multiple issues in a single pull request. + In some cases, you might even resolve a single issue with multiple PRs (e.g. if you are changing multiple implementations). +* Include [tests](TESTING.md) when contributing code. + There are tests that you can use as examples. ## Contributing a new implementation -If you have an implementation in your own repository, that's great! Just add a link to it in our [wiki](https://github.com/google/open-location-code/wiki/Other-Implementations). - -Follow this process for contributing a new implementation: +If you have an implementation in your own repository, that's great! +Unfortunately we can't accept implementations in languages we're not familiar with as we won't be able to maintain or test them. +You can add a link to it in our [list of external implementations](Documentation/External_Implementations.md). * Look at the existing implementations, to get an idea of the usage and how much work is involved. * If you copy the code structure and algorithms from an existing implementation, you'll have a much shorter review cycle. * [Create a new GitHub issue](https://github.com/google/open-location-code/issues/new) to start discussion of the new feature. * Follow the guidelines for [Contributing code](#contributing-code) described above. +* Don't forget to add tests! ## Contributor License Agreement The Open Location Code project hosted at GitHub requires all contributors to sign a Contributor License Agreement ([individual](https://developers.google.com/open-source/cla/individual) or [corporation](https://developers.google.com/open-source/cla/corporate)) in order to protect contributors, users and Google in issues of intellectual property. -When you create a Pull Request, a check will be run to ensure that you have signed the CLA. Make sure that you sign the CLA with the same email address you associate with your commits (likely via the `user.email` Git config as described on GitHub's [Set up Git](https://help.github.com/articles/set-up-git/) page). +When you create a Pull Request, a check will be run to ensure that you have signed the CLA. +Make sure that you sign the CLA with the same email address you associate with your commits (likely via the `user.email` Git config as described on GitHub's [Set up Git](https://help.github.com/articles/set-up-git/) page). ## Ongoing participation diff --git a/Documentation/Reference/App_Developers.md b/Documentation/Reference/App_Developers.md index 38dd60a7..72b01b70 100644 --- a/Documentation/Reference/App_Developers.md +++ b/Documentation/Reference/App_Developers.md @@ -3,7 +3,7 @@ This page gives guidelines for how to support plus codes in a website or mapping application. These guidelines should make it clear that adding support for OLC is not onerous, but actually quite easy. -> Note that with the availability of the [plus codes API](https://github.com/google/open-location-code/wiki/Plus-code-API), these instructions really only apply to apps that require offline support. +> Note that with the availability of the [https://plus.codes website API](plus.codes_Website_API.md), these instructions really only apply to apps that require offline support. If your app or site can rely on a network connection, integrating with the API will give a better solution. # Supporting plus codes for search diff --git a/Documentation/Reference/GIS_Software.md b/Documentation/Reference/GIS_Software.md index 95aa14b8..36fac501 100644 --- a/Documentation/Reference/GIS_Software.md +++ b/Documentation/Reference/GIS_Software.md @@ -7,7 +7,7 @@ This page provides information about using plus codes in GIS software. If you want to visualise the plus codes grid, you can use the [grid service](https://grid.plus.codes) to fetch the grid tiles. This is a shared service, and it may rate limit you. -If you need to use the grid heavily, you can start your own [tile_server](https://github.com/google/open-location-code/tree/master/tile_server). +If you need to use the grid heavily, you can start your own [tile_server](https://github.com/google/open-location-code/blob/main/tile_server). The tile service provides GeoJSON objects, one per plus codes square, or PNG images that can be added as an overlay. diff --git a/Documentation/Reference/Using_Spreadsheets.md b/Documentation/Reference/Using_Spreadsheets.md index e68c8c25..51d705a1 100644 --- a/Documentation/Reference/Using_Spreadsheets.md +++ b/Documentation/Reference/Using_Spreadsheets.md @@ -12,7 +12,7 @@ The [plus codes youtube channel](https://www.youtube.com/c/pluscodes) has some [ ## Excel/LibreOffice -VBA script and instructions are checked into github [here](https://github.com/google/open-location-code/tree/master/visualbasic). +VBA script and instructions are checked into github [here](https://github.com/google/open-location-code/blob/main/visualbasic). LibreOffice does sometimes have problems. This may be due to slightly unreliable VBA support in some versions. diff --git a/Documentation/Reference/comparison.adoc b/Documentation/Reference/comparison.adoc index 018433bf..18ac7ba4 100644 --- a/Documentation/Reference/comparison.adoc +++ b/Documentation/Reference/comparison.adoc @@ -153,7 +153,7 @@ Open Post Codes <> can be defined globally or within a contai Codes, but codes defined within a country are shorter than full Open Location Codes, and a similar length to short Open Location Codes. -Four countries are defined: Ireland, Hong Kong, Yemen and India. +Four countries are defined: Ireland, Hong Kong, Yemen and India. Every location on the planet has a global code. Locations within the countries where Open Post Code has been defined also have a local code. @@ -249,7 +249,7 @@ information such as contact details, photos etc in addition to the location. We felt that the attributes of the above systems didn't sufficiently meet our requirements. As a result, we defined a new coding system and termed it -Open Location Code; codes created using this system are referred to as 'plus codes' (see the link:https://github.com/google/open-location-code/wiki/Naming-Guidelines[Naming Guidelines]). +Open Location Code; codes created using this system are referred to as 'plus codes' (see the link:../Specification/Naming_Guidelines.md[Naming Guidelines]). Plus codes are 10 to 11 characters long. They can also be used in a short form of four to seven characters, similar to telephone numbers and diff --git a/README.md b/README.md index 7f7bd971..9949fe1e 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Codes can be shortened for easier communication, in which case they can be used Algorithms to * encode and decode full codes, * shorten them relative to a reference location, and -* recover a location from a short code and a reference location given as latitude/longitude pair +* recover a location from a short code and a reference location given as latitude/longitude pair are publicly available and can be used without restriction. Geocoding services are not a part of the Open Location Code technology. @@ -33,8 +33,8 @@ Links ----- * [Demonstration site](http://plus.codes/) * [Mailing list](https://groups.google.com/forum/#!forum/open-location-code) - * [Comparison of existing location encoding systems](https://github.com/google/open-location-code/wiki/Evaluation-of-Location-Encoding-Systems) - * [Open Location Code definition](https://github.com/google/open-location-code/blob/master/docs/olc_definition.adoc) + * [Comparison of existing location encoding systems](Documentation/Reference/comparison.adoc) + * [Open Location Code definition](Documentation/Specification/olc_definition.adoc) Description ----------- @@ -74,7 +74,7 @@ Rather than a large city size feature to generate the reference location, it is better to use smaller, neighbourhood features, that will not have as much variation in their geocode results. -Guidelines for shortening codes are in the [wiki](https://github.com/google/open-location-code/wiki/Guidance-for-shortening-codes). +Guidelines for shortening codes are in the [wiki](Documentation/Specification/Short_Code_Guidance.md). Recovering shortened codes works by providing the short code and a reference location. This does not need to be the same as the location used to shorten the diff --git a/TESTING.md b/TESTING.md index e4bc411e..7757feeb 100644 --- a/TESTING.md +++ b/TESTING.md @@ -1,5 +1,5 @@ # Testing -The preferred mechanism for testing is using the [Bazel](https://bazel.build/) build system. This uses files called `BUILD` ([example](https://github.com/google/open-location-code/blob/master/BUILD) to provide rules to build code and run tests). +The preferred mechanism for testing is using the [Bazel](https://bazel.build/) build system. This uses files called `BUILD` ([example](https://github.com/google/open-location-code/blob/main/python/BUILD) to provide rules to build code and run tests). Create a `BUILD` file in your code directory with a [test rule](https://bazel.build/versions/master/docs/test-encyclopedia.html). You can then test your code by running: @@ -57,7 +57,7 @@ An example of a language using bazel is Python: name: test-python-${{ matrix.python }} steps: - uses: actions/checkout@v2 - - name: Set up Python + - name: Set up Python uses: actions/setup-python@v2 with: python-version: ${{ matrix.python }} diff --git a/java/README.md b/java/README.md index d3ab7b39..6e55efc3 100644 --- a/java/README.md +++ b/java/README.md @@ -20,7 +20,7 @@ executed by running `mvn pmd:pmd pmd:check`. ## Building and Testing -Note: the tests read their data from the [`test_data`](https://github.com/google/open-location-code/tree/master/test_data) directory. +Note: the tests read their data from the [`test_data`](https://github.com/google/open-location-code/blob/main/test_data) directory. ### Maven diff --git a/js/closure/README.md b/js/closure/README.md index 2f216b9a..c0c1c1ac 100644 --- a/js/closure/README.md +++ b/js/closure/README.md @@ -33,7 +33,7 @@ Included is a `BUILD` file that uses the [Bazel](https://bazel.build/) build sys The tests use the [Closure Rules for Basel](https://github.com/bazelbuild/rules_closure) project although this is retrieved automatically and you don't have to install anything. -The test cases have been copied from the [`test_data`](https://github.com/google/open-location-code/tree/master/test_data) directory due to restrictions on loading data files within the test runner. +The test cases have been copied from the [`test_data`](https://github.com/google/open-location-code/blob/main/test_data) directory due to restrictions on loading data files within the test runner. Run the tests from the top-level github directory with: