|
| 1 | +# Osm2pgsql contribution guidelines |
| 2 | + |
| 3 | +## Workflow |
| 4 | + |
| 5 | +We operate the "Fork & Pull" model explained at |
| 6 | + |
| 7 | +https://help.github.com/articles/using-pull-requests |
| 8 | + |
| 9 | +You should fork the project into your own repo, create a topic branch |
| 10 | +there and then make one or more pull requests back to the openstreetmap repository. |
| 11 | +Your pull requests will then be reviewed and discussed. |
| 12 | + |
| 13 | +## History |
| 14 | + |
| 15 | +To understand the osm2pgsql code, it helps to know some history on it. Osm2pgsql |
| 16 | +was written in C in 2007 as a port of an older Python utility. In 2014 it was |
| 17 | +ported to C++ by MapQuest and the last C version was released as 0.86.0. In it's |
| 18 | +time, it has had varying contribution activity, including times with no |
| 19 | +maintainer or active developers. |
| 20 | + |
| 21 | +Parts of the codebase still clearly show their C origin and could use rewriting |
| 22 | +in modern C++, making use of data structures in the standard library. |
| 23 | + |
| 24 | +## Versioning |
| 25 | + |
| 26 | +Osm2pgsql uses a X.Y.Z version number, where Y tells you if you are on a stable |
| 27 | +or development series. Like the Linux Kernel, even numbers are stable and |
| 28 | +development versions are odd. |
| 29 | + |
| 30 | +Bugs and known issues are fixed on the main branch only. Exceptions may be made |
| 31 | +for easy bug fixes, or if a patch backporting a fix is provided. |
| 32 | + |
| 33 | +## Code style |
| 34 | + |
| 35 | +The current codebase is a mix of styles, but new code should be written in the |
| 36 | +[K&R 1TBS style](https://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS) with |
| 37 | +4 spaces indentation. Tabs should never be used in the C++ code. |
| 38 | + |
| 39 | +e.g. |
| 40 | + |
| 41 | +``` |
| 42 | +int main(int argc, char *argv[]) |
| 43 | +{ |
| 44 | + ... |
| 45 | + while (x == y) { |
| 46 | + something(); |
| 47 | + somethingelse(); |
| 48 | +
|
| 49 | + if (some_error) { |
| 50 | + do_correct(); |
| 51 | + } else { |
| 52 | + continue_as_usual(); |
| 53 | + } |
| 54 | + } |
| 55 | +
|
| 56 | + finalthing(); |
| 57 | + ... |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +Names should use underscores, not camel case, with class/struct names ending in `_t`. |
| 62 | + |
| 63 | +## Platforms targeted |
| 64 | + |
| 65 | +Ideally osm2pgsql should compile on Linux, OS X, FreeBSD and Windows. It is |
| 66 | +actively tested on Debian, Ubuntu and FreeBSD by the maintainers. |
| 67 | + |
| 68 | +## Testing |
| 69 | + |
| 70 | +The code also comes with a suite of tests which can be run by |
| 71 | +executing ``make check``. |
| 72 | + |
| 73 | +Most of these tests depend on being able to set up a database and run osm2pgsql |
| 74 | +against it. You need to ensure that PostgreSQL is running and that your user is |
| 75 | +a superuser of that system. To do that, run: |
| 76 | + |
| 77 | +```sh |
| 78 | +sudo -u postgres createuser -s $USER |
| 79 | +sudo mkdir -p /tmp/psql-tablespace |
| 80 | +sudo chown postgres.postgres /tmp/psql-tablespace |
| 81 | +psql -c "CREATE TABLESPACE tablespacetest LOCATION '/tmp/psql-tablespace'" postgres |
| 82 | +``` |
| 83 | + |
| 84 | +Once this is all set up, all the tests should run (no SKIPs), and pass |
| 85 | +(no FAILs). If you encounter a failure, you can find more information |
| 86 | +by looking in the `test-suite.log`. If you find something which seems |
| 87 | +to be a bug, please check to see if it is a known issue at |
| 88 | +https://github.com/openstreetmap/osm2pgsql/issues and, if it's not |
| 89 | +already known, report it there. |
| 90 | + |
| 91 | +If running the tests in a virtual machine, allocate sufficient disk space for a |
| 92 | +20GB flat nodes file. |
| 93 | + |
| 94 | +### Performance Testing |
| 95 | + |
| 96 | +If performance testing with a full planet import is required, indicate what |
| 97 | +needs testing in a pull request. |
| 98 | + |
| 99 | +## Maintainers |
| 100 | + |
| 101 | +The current maintainers of osm2pgsql are [Sarah Hoffmann](https://github.com/lonvia/) |
| 102 | +and [Paul Norman](https://github.com/pnorman/). Sarah has more experience with |
| 103 | +the gazetteer backend and Paul with the pgsql and multi backends. |
0 commit comments