EL-BID · Claudio9701 · Aug 10, 2026
@@ -0,0 +1,53 @@
+# Changelog
+
+All notable user-visible changes are recorded here. UrbanPy follows semantic
+versioning and uses the headings from [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Added
+
+- A uv-managed PEP 621 build with a reproducible development lockfile and Python
+  3.11–3.14 CI matrix.
+- Strict Pydantic boundary models for coordinates, bounding boxes, travel
+  profiles, Geofabrik records, and the OSRM lifecycle.
+- Canonical Geofabrik catalog resolution using official IDs, exact ISO aliases,
+  and provider-advertised PBF URLs.
+- A cross-platform Python OSRM manager with atomic downloads/preparation,
+  pinned containers, ownership protection, readiness checks, and dry-run cleanup.
+- A Docker-independent typed OSRM route/table client.
+- Hermetic provider contract tests, mandatory SonarQube enforcement, Trunk code
+  quality, dependency auditing, and agent governance.
+
+### Changed
+
+- H3 4.x, OSMnx 2.x, GeoPandas 1.x, and current HDX behavior are supported and
+  regression-tested.
+- OSRM durations are documented in seconds, matching the upstream API.
+- Geospatial outputs retain their input or declared CRS in the corrected paths.
+- HDX searches use the current client and return stable UrbanPy provider errors.
+
+### Fixed
+
+- `merge_shape_hex` can be rerun on its own result.
+- One-resource HDX selections no longer pass a pandas Series to `read_csv`.
+- OSMnx nearest-node coordinate order and graph isochrone coordinate fields.
+- OSRM nested Geofabrik regions, platform divergence, false readiness, unsafe
+  container collisions, partial downloads, and incorrect MLD path extensions.
+
+### Deprecated
+
+- `start_osrm_server` and `stop_osrm_server`; migrate to `OSRMConfig` and
+  `OSRMManager` before the next breaking release.
+
+### Removed
+
+- The unsupported OSRM Bash, PowerShell, legacy class, and notebook launchers.
+
+## [0.2.2] - 2024-07-18
+
+The historical release predates the structured changelog. See the
+[GitHub release](https://github.com/EL-BID/urbanpy/releases/tag/v0.2.2).
+
+[Unreleased]: https://github.com/EL-BID/urbanpy/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/EL-BID/urbanpy/releases/tag/v0.2.2
@@ -0,0 +1,34 @@
+cff-version: 1.2.0
+message: "If you use UrbanPy, please cite the software and its reference paper."
+title: "UrbanPy"
+type: software
+version: 0.3.0a0
+license: GPL-3.0-only
+repository-code: "https://github.com/EL-BID/urbanpy"
+url: "https://el-bid.github.io/urbanpy/"
+authors:
+  - family-names: Regal
+    given-names: Andres
+  - family-names: Ortega
+    given-names: Claudio
+  - family-names: Vazquez Brust
+    given-names: Antonio
+preferred-citation:
+  type: conference-paper
+  title: "UrbanPy: A Library to Download, Process and Visualize High Resolution Urban Data to Support Transportation and Urban Planning Decisions"
+  year: 2022
+  doi: 10.1007/978-3-031-06862-1_34
+  collection-title: "Production and Operations Management"
+  publisher:
+    name: Springer International Publishing
+  authors:
+    - family-names: Regal
+      given-names: Andres
+    - family-names: Ortega
+      given-names: Claudio
+    - family-names: Vazquez Brust
+      given-names: Antonio
+    - family-names: Rodriguez
+      given-names: Michelle
+    - family-names: Zambrano-Barragan
+      given-names: Patricio
@@ -0,0 +1,35 @@
+# Governance
+
+UrbanPy is an EL-BID open-source project maintained in public on GitHub.
+
+## Roles and decisions
+
+Maintainers triage issues, define supported APIs, review contributions, manage
+security reports, and approve releases. Contributors propose work through issues
+and pull requests. Technical decisions are documented in the relevant issue or
+PR; public API, dependency, data-license, security, and migration impact must be
+explicit.
+
+Changes are accepted by maintainer review after required automation is green.
+SonarQube is mandatory under EL-BID policy. Dependency/license findings require
+an explicit maintainer disposition and are not dismissed by automation.
+
+## Automation and agents
+
+Automation may create branches, issues, and dependency-ordered pull requests.
+It may not approve or merge its own work, publish packages, change repository
+secrets or branch protection, or dismiss security and license findings. Human
+maintainers retain release and administrative authority. The repository's
+`AGENTS.md`, CODEOWNERS, and pull-request template define the operational rules.
+
+## Releases and compatibility
+
+UrbanPy follows semantic versioning. Deprecations emit a documented warning for
+at least one minor release when practical. Breaking changes require an issue,
+migration notes, and a major version unless needed to correct a security or data
+integrity defect during a prerelease.
+
+Release artifacts are built once from a reviewed tag and promoted through
+protected environments. A maintainer approves publication and post-release
+support. The release-engineering workstream maintains the operational runbook
+alongside the publish workflows.
@@ -1,15 +1,16 @@
-[![Test and deploy](https://github.com/EL-BID/urbanpy/actions/workflows/main.yml/badge.svg)](https://github.com/EL-BID/urbanpy/actions/workflows/main.yml)
+[![CI](https://github.com/EL-BID/urbanpy/actions/workflows/main.yml/badge.svg)](https://github.com/EL-BID/urbanpy/actions/workflows/main.yml)
+[![SonarQube](https://github.com/EL-BID/urbanpy/actions/workflows/build.yml/badge.svg)](https://github.com/EL-BID/urbanpy/actions/workflows/build.yml)
 [![Downloads](https://static.pepy.tech/badge/urbanpy)](https://pepy.tech/project/urbanpy)
 [![Downloads](https://static.pepy.tech/badge/urbanpy/month)](https://pepy.tech/project/urbanpy)
 [![Downloads](https://static.pepy.tech/badge/urbanpy/week)](https://pepy.tech/project/urbanpy)
-![analytics image (flat)](https://raw.githubusercontent.com/vitr/google-analytics-beacon/master/static/badge.svg)
-![analytics](https://www.google-analytics.com/collect?v=1&cid=555&t=pageview&ec=repo&ea=open&dp=/urbanpy/readme&dt=&tid=UA-4677001-16)
+# UrbanPy 🏙️
 
-# Welcome to UrbanPy :city_sunrise:
+**Download, process, route, and visualize high-resolution urban geospatial data.**
 
-**A library to download, process and visualize high resolution urban data in an easy and fast way.**
-
-UrbanPy is an open source project to automate data extraction, measurement, and visualization of urban accessibility metrics.
+UrbanPy is an EL-BID open-source Python library for reproducible urban data and
+accessibility workflows. Version 0.3 is currently an alpha modernization: use a
+stable 0.2 release for established production deployments and test 0.3 against
+your data before upgrading.
 
 # Functional goals
 
@@ -40,28 +41,26 @@ UrbanPy is an open source project to automate data extraction, measurement, and
 
 ### For users
 
-To install the urbanpy library you can use:
+Install the stable release from PyPI:
 
 ```sh
-$ pip install urbanpy
+python -m pip install urbanpy
 ```
 
 Then use `import urbanpy` in your python scripts to use the library.
 
-If you plan to use the [OSRM Server](http://project-osrm.org/) route or distance matrix calculation functionalities\* you must have Docker installed in your system, refer to Docker [Installation](https://www.docker.com/products/docker-desktop). For Windows users, make sure to run the following command in powershell to avoid execution errors.
-
-```powershell
-    Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
-```
-
-### Additional Dependecies Notes
-
-- It is important to note that for travel time computation, if needed, a method is implements the Open Source Routing Machine (OSRM). This method pulls, extracts and adds graph weights to the downloaded network and runs the routing server. Make sure to have docker installed for the library to work correctly. Also, verify in the docker settings that containers can use the necessary cpu cores and ram memory (it depends in the country size).
+The normal routing, geometry, and provider clients do not require a local OSRM
+container. To prepare and operate a local OSRM service, install Docker and follow
+the [OSRM guide](https://el-bid.github.io/urbanpy/usage/osrm.html). UrbanPy 0.3
+uses a cross-platform Python lifecycle; it never requires weakening PowerShell's
+execution policy.
 
-- Urbanpy provides a simple approximation with nearest neighbor search using a BallTree and haversine distance, but the difference between real travel time and the approximation may vary from city to city.
+### Geospatial dependencies
 
-- Additionally, the use of spatial libraries like osmnx, geopandas and h3 require certain extra packages. Specifically, for rtree (spatial indexing to allow spatial joins) libspatialindex is required. OSMnx and Geopandas requiere GDAL as well. If not handled by installing geopandas's dependencies, installing fiona, pyproj and shapely should satisfy the requirements. Another way to ensure all dependencies are met, installing osmnx via conda should suffice. H3 requires cc, make, and cmake in your $PATH when installing, otherwise installation will not be successful. Please refer to [h3's documentation](https://github.com/uber/h3) for a more
-  detailed guide on installation options and requirements.
+Current GeoPandas, Shapely, OSMnx, and H3 releases provide wheels for common
+platforms. If installation must compile a dependency, install that project's
+documented system toolchain. Large OSRM regions require substantial disk, memory,
+and processing time; begin with a small canonical Geofabrik region.
 
 # Examples
 
@@ -80,28 +79,24 @@ Since `boundaries` is a GeoDataFrame it can be easily plotted with the method `.
 hexes = up.geom.gen_hexagons(resolution=9, city=boundaries)
 ```
 
-Also check our [example notebooks](https://nbviewer.org/github/EL-BID/urbanpy/tree/master/notebooks/), and if you have examples or visualizations of your own, we encourage you to share contribute.
+See the [documentation](https://el-bid.github.io/urbanpy/) and
+[example notebooks](https://nbviewer.org/github/EL-BID/urbanpy/tree/master/notebooks/).
 
 ### For developers
 
-If you plan to contribute or customize urbanpy first clone this repo and cd into it. Then, we strongly recommend you to create a virtual environment. You can use conda, this installation manage some complicated C spatial library dependencies:
-
-```sh
-$ conda env create -n urbanpy -f environment.yml python=3.6
-$ conda activate urbanpy
-```
-
-Or if you are more confident about your setup, you can use pip:
+Install [uv](https://docs.astral.sh/uv/), clone the repository, and create the
+locked development environment:
 
 ```sh
-$ python3 -m venv .env
-$ source .env/bin/activate
-(.env) $ pip install -r requirements.txt
+uv sync --locked --all-groups
+uv run pytest
+trunk check
 ```
 
 ## License
 
-UrbanPy is licensed under the [GPL-3](LICENSE) license.
+UrbanPy is licensed under [GPL-3.0-only](LICENSE). Data downloaded through
+UrbanPy remains subject to each provider's terms and license.
 
 ## Authors
 
@@ -114,7 +109,10 @@ UrbanPy's original authors are Claudio Ortega ([socials](https://www.linkedin.co
 [code of conduct](CODE_OF_CONDUCT.md). By participating, you are expected to
 uphold this code.**
 
-\*Current support is tested on Linux Ubuntu 18.04 & Mac OS Catalina, coming soon we will test and support Windows 10.
+See [SUPPORT.md](SUPPORT.md), [GOVERNANCE.md](GOVERNANCE.md), and
+[SECURITY.md](SECURITY.md) for maintenance, decision-making, and private
+vulnerability reporting. Supported Python versions are tested in CI; OSRM
+platform claims require separate Docker release evidence.
 
 ## Citation
 
@@ -129,7 +127,7 @@ If you use this library or find the documentation useful for your research, plea
     publisher="Springer International Publishing",
     address="Cham",
     pages="463--473",
-    isbn="978-3-031-06862-1"
+    isbn="978-3-031-06862-1",
     url="https://doi.org/10.1007/978-3-031-06862-1_34"
 }
 ```

@@ -0,0 +1,36 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made on the default branch and released in the newest
+maintained minor series. During the 0.3 prerelease cycle, `0.3.0a*`, `0.3.0b*`,
+and `0.3.0rc*` are evaluation builds and may receive breaking fixes. The 0.2
+series receives critical fixes only until 0.3.0 is stable; older versions are
+unsupported.
+
+## Report a vulnerability privately
+
+Do not disclose vulnerabilities in a public issue, pull request, discussion,
+notebook, or chat. Use **Security → Advisories → Report a vulnerability** in
+the [UrbanPy repository](https://github.com/EL-BID/urbanpy/security/advisories/new).
+GitHub private vulnerability reporting is enabled for this repository.
+
+Include the affected version or commit, impact, reproduction prerequisites,
+minimal proof of concept, and any suggested mitigation. Remove credentials,
+personal data, and sensitive provider responses.
+
+Maintainers aim to acknowledge a report within five working days, provide a
+triage decision within ten working days, and coordinate publication after a fix
+is available. These are response targets, not a bug-bounty or compensation
+commitment.
+
+## Scope
+
+UrbanPy code, packaging, published artifacts, release automation, and unsafe
+handling of external data are in scope. Vulnerabilities in upstream services or
+dependencies should also be reported to their owners; tell UrbanPy privately
+when the library needs a mitigation or dependency update.
+
+Security advisories, CVEs when appropriate, patched-version ranges, and upgrade
+instructions are published through GitHub and the changelog. SonarQube remains
+a mandatory EL-BID quality gate and does not replace coordinated disclosure.
@@ -0,0 +1,20 @@
+# Support policy
+
+UrbanPy is community-maintained open-source software. Public support is provided
+on a best-effort basis; no service-level agreement is implied.
+
+- Use [GitHub Issues](https://github.com/EL-BID/urbanpy/issues) for reproducible
+  bugs and scoped feature proposals.
+- Use the bug form and include UrbanPy/Python versions, operating system, CRS,
+  a minimal synthetic example, and redacted logs.
+- Search existing issues before opening a new report.
+- Do not use public issues for vulnerabilities; follow [SECURITY.md](SECURITY.md).
+- Questions about institutional deployments, private data, or EL-BID policy
+  should use the appropriate institutional support channel rather than the
+  public tracker.
+
+The supported Python range is declared in `pyproject.toml` and exercised in CI.
+Provider-backed features depend on third-party availability and policy; unit
+tests use captured contracts, while scheduled live checks detect upstream drift.
+Docker-backed OSRM support is limited to platforms for which release evidence is
+recorded. See the OSRM guide before processing large regions.