diff --git a/AUTHORS b/AUTHORS index af8498b00..0f6bbfa4b 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,3 +1,3 @@ osm2pgsql was written by Jon Burgess, Artem Pavlenko, Martijn van Oosterhout -Sarah Hoffman, Kai Krueger, Frederik Ramm, Brian Quinion and other -OpenStreetMap project members. \ No newline at end of file +Sarah Hoffmann, Kai Krueger, Frederik Ramm, Brian Quinion, Matt Amos, +Kevin Kreiser, Paul Norman and other OpenStreetMap project members. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..27bb5ca51 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,102 @@ +# Osm2pgsql contribution guidelines + +## Workflow + +We operate the "Fork & Pull" model explained at + +https://help.github.com/articles/using-pull-requests + +You should fork the project into your own repo, create a topic branch +there and then make one or more pull requests back to the openstreetmap repository. +Your pull requests will then be reviewed and discussed. + +## History + +To understand the osm2pgsql code, it helps to know some history on it. Osm2pgsql +was written in C in 2007 as a port of an older Python utility. In 2014 it was +ported to C++ by MapQuest and the last C version was released as 0.86.0. In it's +time, it has had varying contribution activity, including times with no +maintainer or active developers. + +Parts of the codebase still clearly show their C origin and could use rewriting +in modern C++, making use of data structures in the standard library. + +## Versioning + +Osm2pgsql uses a X.Y.Z version number, where Y tells you if you are on a stable +or development series. Like the Linux Kernel, even numbers are stable and +development versions are odd. + +Old branches and versions are not generally maintained. + +## Code style + +The current codebase is a mix of styles, but new code should be written in the +[K&R 1TBS style](https://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS) with +4 spaces indentation. Tabs should never be used in the C++ code. + +e.g. + +``` +int main(int argc, char *argv[]) +{ + ... + while (x == y) { + something(); + somethingelse(); + + if (some_error) { + do_correct(); + } else { + continue_as_usual(); + } + } + + finalthing(); + ... +} +``` + +Names should use underscores, not camel case, with class/struct names ending in `_t`. + +## Platforms targeted + +Ideally osm2pgsql should compile on Linux, OS X, FreeBSD and Windows. It is +actively tested on Debian, Ubuntu and FreeBSD by the maintainers. + +## Testing + +The code also comes with a suite of tests which can be run by +executing ``make check``. + +Most of these tests depend on being able to set up a database and run osm2pgsql +against it. You need to ensure that PostgreSQL is running and that your user is +a superuser of that system. To do that, run: + +```sh +sudo -u postgres createuser -s $USER +sudo mkdir -p /tmp/psql-tablespace +sudo chown postgres.postgres /tmp/psql-tablespace +psql -c "CREATE TABLESPACE tablespacetest LOCATION '/tmp/psql-tablespace'" postgres +``` + +Once this is all set up, all the tests should run (no SKIPs), and pass +(no FAILs). If you encounter a failure, you can find more information +by looking in the `test-suite.log`. If you find something which seems +to be a bug, please check to see if it is a known issue at +https://github.com/openstreetmap/osm2pgsql/issues and, if it's not +already known, report it there. + +If running the tests in a virtual machine, allocate sufficient disk space for a +20GB flat nodes file. + +### Performance Testing + +If performance testing with a full planet import is required, indicate what +needs testing in a pull request. + +## Maintainers + +The current maintainers of osm2pgsql are [Sarah Hoffmann](https://github.com/lonvia/) +and [Paul Norman](https://github.com/pnorman/). Sarah has more experience with +the gazetteer backend and Paul with the pgsql and multi backends. diff --git a/README.md b/README.md index f6bdd6893..b601b8ccc 100644 --- a/README.md +++ b/README.md @@ -143,33 +143,12 @@ postgres tables instead of those provided in the pgsql backend. Any questions should be directed at the osm dev list http://wiki.openstreetmap.org/index.php/Mailing_lists -## Testing ## - -The code also comes with a suite of tests which can be run by -executing ``make check``. - -Some of these tests depend on being able to set up a database and run -osm2pgsql against it. You need to ensure that PostgreSQL is running -and that your user is a superuser of that system. To do that, run: - -```sh -sudo -u postgres createuser -s $USER -sudo mkdir -p /tmp/psql-tablespace -sudo chown postgres.postgres /tmp/psql-tablespace -psql -c "CREATE TABLESPACE tablespacetest LOCATION '/tmp/psql-tablespace'" postgres -``` - -Once this is all set up, all the tests should run (no SKIPs), and pass -(no FAILs). If you encounter a failure, you can find more information -by looking in the `test-suite.log`. If you find something which seems -to be a bug, please check to see if it is a known issue at -https://github.com/openstreetmap/osm2pgsql/issues and, if it's not -already known, report it there. - ## Contributing ## We welcome contributions to osm2pgsql. If you would like to report an issue, please use the [issue tracker on GitHub](https://github.com/openstreetmap/osm2pgsql/issues). +More information can be found in [CONTRIBUTING.md](CONTRIBUTING.md). + General queries can be sent to the tile-serving@ or dev@ [mailing lists](http://wiki.openstreetmap.org/wiki/Mailing_lists).