Skip to content

Refresh of README and CONTRIBUTING #2363

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 24, 2025
Merged

Refresh of README and CONTRIBUTING #2363

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf6b101
update feature and installation sections in the README
lonvia Jul 2, 2025
912de14
rework content of CONTRIBUTING
lonvia Jul 19, 2025
279158e
adapt CI status for new repo
lonvia Jul 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 38 additions & 45 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,34 +1,41 @@
# Osm2pgsql contribution guidelines
# 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 its time, it has had varying contribution activity, including times
with no maintainer or active developers.

Very few parts of the code now show their C origin, most has been transformed
to modern C++. We are currently targeting C++17.

## Versioning
The following section describes our work flow, coding style and give some
hints on developer setup.
For more information about what to contribute and an overview
of the general roadmap, visit the [Contribution guide](https://osm2pgsql.org/contribute/)
on the osm2pgsql website.

Osm2pgsql uses [semantic versioning](https://semver.org/).

Bugs and known issues are fixed on the main branch only. Exceptions may be made
for severe bugs.
## Workflow

## Code style
We operate with the
["Fork & Pull"](https://help.github.com/articles/using-pull-requests) model
and try to stick to a four-eyes review mode, meaning that PRs should be merged
by a different person than the author.

Here are a few simple rules you should follow with your code and pull request (PR).
They will maximize your chances that a PR gets reviewed and merged.

* Split your PR into functionally sensible commits. Describe each commit with
a relevant commit message. If you need to do fix-up commits, please, merge
them into the functional commits. Interactive rebasing (`git rebase -i`) is
very useful for this. Then force-push to your PR branch.
* Avoid merge commits. If you have to catch up with changes from master,
rather use rebasing.
* Split up larger PRs into smaller units if possible. Never mix two different
topics or fixes in a single PR.
* Decorate your PR with an informative but succinct description. Do not post
AI-generated PR descriptions without having reviewed (and preferably heavily
shortened) the text.
* Try to follow the style of existing code as close as possible. Use
clang-format to follow the formal coding style (see below).

> [!IMPORTANT]
> Any use of generative AI for writing code, documentation or PR descriptions
> must be disclosed. You must further be able to show that you have understood
> the generated parts. Your code, your responsibility.

## Coding style

Code must be written in the
[K&R 1TBS style](https://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS) with
Expand Down Expand Up @@ -75,17 +82,8 @@ installed with:
sudo apt-get install pandoc python3-argparse-manpage
```

Results should be checked into the repository.

## Platforms targeted

Osm2pgsql must compile and pass all tests at least on Linux, OS X and Windows.
Tests run on Github action to make sure that it does.

On Linux the latest stable versions of popular distributions and the stable
version before that are supported if possible.

All maintained versions of PostgreSQL are supported.
The manpages are rebuilt and checked into the repository as part of the
release process.

## Testing

Expand All @@ -107,7 +105,7 @@ against it. This is most easily done using `pg_virtualenv`. Just run
pg_virtualenv ctest
```

`pg_virtualenv` creates a separate postgres server instance. The test databases
`pg_virtualenv` creates a separate PostgreSQL server instance. The test databases
are created in this instance and the complete server is destroyed after the
tests are finished. ctest also calls appropriate fixtures that create the
separate tablespace required for some tests.
Expand Down Expand Up @@ -221,8 +219,3 @@ the report.
* Copy Windows binaries and source tarball to osm2pgsql.org.
* Add release info to osm2pgsql.org.
* Publish release notes as News article on osm2pgsql.org.

## Maintainers

The current maintainers of osm2pgsql are [Sarah Hoffmann](https://github.com/lonvia/)
and [Paul Norman](https://github.com/pnorman/).
60 changes: 35 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,36 +9,40 @@ Nominatim, or general analysis.
See the [documentation](https://osm2pgsql.org/doc/) for instructions on how
to install and run osm2pgsql.

[![Github Actions Build Status](https://github.com/openstreetmap/osm2pgsql/workflows/CI/badge.svg?branch=master)](https://github.com/openstreetmap/osm2pgsql/actions)
[![Github Actions Build Status](https://github.com/osm2pgsql-dev/osm2pgsql/workflows/CI/badge.svg)](https://github.com/osm2pgsql-dev/osm2pgsql/actions)
[![Packaging Status](https://repology.org/badge/tiny-repos/osm2pgsql.svg)](https://repology.org/project/osm2pgsql/versions)

## Features

* Converts OSM files to a PostgreSQL DB
* Conversion of tags to columns is configurable in the style file
* Able to read .gz, .bz2, .pbf and .o5m files directly
* Can apply diffs to keep the database up to date
* Support the choice of output projection
* Configurable table names
* Support for hstore field type to store the complete set of tags in one database
field if desired
* freely configurable table layout and content using the LUA scripting language
* support for building geometries in simple feature format and for generalization
* read OSM data from OSM, PBF and O5M formats
* update the database from OSM change files and replication diffs
* usable for importing a small geographic area on a tiny laptop up to
importing the whole world on a large server machine
* runs on Linux, Windows and MacOS
* [and more](https://osm2pgsql.org/about/features/)

## Installing

Most Linux distributions include osm2pgsql. It is available on macOS with
[Homebrew](https://brew.sh/) and Windows builds are also available. See
https://osm2pgsql.org/doc/install.html for details.
* __Linux__: most distributions include osm2pgsql. Debian always offers
the latest version via backports.
* __macOS__: osm2pgsql is available through [Homebrew](https://brew.sh/)
* __Windows__: use our [binary builds](https://osm2pgsql.org/download/windows/)

For detailed instructions, visit
the [Installation page](https://osm2pgsql.org/doc/install.html).

## Building

The latest source code is available in the osm2pgsql git repository on GitHub
and can be downloaded as follows:

```sh
git clone https://github.com/openstreetmap/osm2pgsql.git
git clone https://github.com/osm2pgsql-dev/osm2pgsql.git
```

Osm2pgsql uses the cross-platform [CMake build system](https://cmake.org/)
osm2pgsql uses the cross-platform [CMake build system](https://cmake.org/)
to configure and build itself.

Required libraries are
Expand All @@ -50,16 +54,16 @@ Required libraries are
* [zlib](https://www.zlib.net/)
* [Boost libraries](https://www.boost.org/) (for boost geometry)
* [nlohmann/json](https://json.nlohmann.me/)
* [OpenCV](https://opencv.org/) (Optional, for generalization only)
* [potrace](https://potrace.sourceforge.net/) (Optional, for generalization only)
* [PostgreSQL](https://www.postgresql.org/) client libraries
* [PostgreSQL](https://www.postgresql.org/) client library
* [Lua](https://www.lua.org/)
* [OpenCV](https://opencv.org/) (optional, for generalization only)
* [potrace](https://potrace.sourceforge.net/) (optional, for generalization only)
* [Python](https://python.org/) (only for running tests)
* [Psycopg](https://www.psycopg.org/) (only for running tests)

The following libraries are included in the `contrib` directory. You can build
with other versions of those libraries (set the `EXTERNAL_*libname*` option to
`ON`) but make sure you are using a compatible version:
with other versions of those libraries (set the `EXTERNAL_*libname*` CMake
option to `ON`) but make sure you are using a compatible version:

* [fmt](https://fmt.dev/) (>= 7.1.3)
* [libosmium](https://osmcode.org/libosmium/) (>= 2.17.0)
Expand All @@ -73,7 +77,7 @@ Make sure you have installed the development packages for the libraries
mentioned in the requirements section and a C++ compiler which supports C++17.
We officially support gcc >= 10.0 and clang >= 13.

To rebuild the included man page you'll need the [pandoc](https://pandoc.org/)
To rebuild the included man page you need the [pandoc](https://pandoc.org/)
tool.

First install the dependencies.
Expand Down Expand Up @@ -150,8 +154,8 @@ The compiled files can be installed with
sudo make install
```

By default, the Release build with debug info is created and no tests are
compiled. You can change that behavior by using additional options like
By default, a Release build with debug info is created and tests are
disabled. You can change that behavior by using additional options like
following:

```sh
Expand All @@ -163,12 +167,13 @@ Note that `Debug` builds will be much slower than release build. For production

### Using the PROJ library

Osm2pgsql has builtin support for the Latlong (WGS84, EPSG:4326) and the
osm2pgsql has builtin support for the Latlong (WGS84, EPSG:4326) and the
WebMercator (EPSG:3857) projection. Other projections are supported through
the [Proj library](https://proj.org/) which is used by default. Set the CMake
the [Proj library](https://proj.org/). Support will be automatically compiled
in, when CMake can find the library in the system. Set the CMake
option `WITH_PROJ` to `OFF` to disable use of that library.

## Using LuaJIT
### Using LuaJIT

To speed up Lua tag transformations, [LuaJIT](https://luajit.org/) can be
optionally enabled on supported platforms. This can speed up processing
Expand Down Expand Up @@ -216,6 +221,11 @@ but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

## Maintainers

The current maintainers of osm2pgsql are [Sarah Hoffmann](https://github.com/lonvia/)
and [Paul Norman](https://github.com/pnorman/).

## Contributing

We welcome contributions to osm2pgsql. See [CONTRIBUTING.md](CONTRIBUTING.md)
Expand Down