diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 988f506..e1ed417 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -32,7 +32,9 @@ Provide a link to a live example, or an unambiguous set of steps to reproduce this bug. Include code to reproduce, if relevant. --> -1. 2. 3. +1. +2. +3. ## Context diff --git a/content/CONTRIBUTING.md b/content/CONTRIBUTING.md index 2f47e55..38d4b9c 100644 --- a/content/CONTRIBUTING.md +++ b/content/CONTRIBUTING.md @@ -27,15 +27,16 @@ the repository of the project you are working on. - Commit messages should follow best practices, including explaining the context of the problem and how it was solved, including in caveats or follow up changes required. They should tell the story of the change and provide readers - understanding of what led to it. Please refer to [How to Write a Git - Commit Message] for more details. -- If your [pull request] is a work in progress, create it as a [draft pull request]. -- Any [pull request] inactive for 28 days will be automatically closed. If you need - more time to work on it, ask maintainers, to add the appropriate label to it. Use - the `@` mention in the comments. -- Unless explicitly asked, [pull request] which don't pass all the CI checks will - not be reviewed. Use the `@` mention in the comments to ask maintainers to help - you. + understanding of what led to it. Please refer to [How to Write a Git Commit + Message] for more details. +- If your [pull request] is a work in progress, create it as a [draft pull + request]. +- Any [pull request] inactive for 28 days will be automatically closed. If you + need more time to work on it, ask maintainers, to add the appropriate label to + it. Use the `@` mention in the comments. +- Unless explicitly asked, [pull request] which don't pass all the CI checks + will not be reviewed. Use the `@` mention in the comments to ask maintainers + to help you. ## Commit example diff --git a/content/_index.md b/content/_index.md index d79c44d..9ffb260 100644 --- a/content/_index.md +++ b/content/_index.md @@ -10,8 +10,8 @@ for the bike industry working to make bicycling safe, convenient, and fun for people of all ages and abilities. The [Bicycle Network Analysis], a.k.a. the BNA, is open source software that assesses the quality and connectivity of bike networks in cities. The [BNA] is an integral part of PeopleForBikes’ [City -Ratings] program, which measures progress towards building great cities for bikes, -shares best practices, and engages more people in bike advocacy. +Ratings] program, which measures progress towards building great cities for +bikes, shares best practices, and engages more people in bike advocacy. **BNA Mechanics** is the technical group developing the [BNA]. We aim to simplify and automate tasks to help our advocates focus on what they do best: diff --git a/content/guidelines.md b/content/guidelines.md index 833bac6..934bb3e 100644 --- a/content/guidelines.md +++ b/content/guidelines.md @@ -71,12 +71,10 @@ projects. - Use linters with default configurations - Unless there is an absolute need for a change -## APIs +## REST APIs -- We follow the [jsonapi.org] specification. -- When in doubt, or if something is unclear in the [jsonapi.org] specification, - refer to the [GitHub REST API] documentation for a well thought real life - example. +- We try to follow the [GitHub REST API] documentation and the [jsonapi.org] + specification for error management. - Zalando provides very good [RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/) worth following @@ -85,19 +83,11 @@ projects. ### Project management -- [poetry]: Python project management de facto standard +- [uv]: The future of Python project management We recommend using [just] for managing administration tasks, but for more complex scenarios [invoke] is an acceptable replacement. -### Poetry settings - -Each project must create a local virtual environment at its root : - -```bash -poetry config virtualenvs.in-project true --local -``` - ### pyproject.toml Describes special sections to add to the `pyproject.toml` configuration file. @@ -138,10 +128,10 @@ addopts = "-p no:warnings --cov-report term-missing --cov-report html --xdoctest To quickly start a project, run the following commands: ```bash -export POETRY_PROJECT=my-project -poetry new ${POETRY_PROJECT} -cd ${POETRY_PROJECT} -poetry add -G dev \ +export PYTHON_PROJECT=my-project +uv init ${PYTHON_PROJECT} +cd ${PYTHON_PROJECT} +uv add --dev \ bpython \ furo\ isort \ @@ -159,6 +149,11 @@ poetry add -G dev \ xdoctest ``` +### Legacy + +- [poetry]: Python project management de facto standard + - This project was replaced by the team in January 2025. + ### Libraries #### Production @@ -207,12 +202,16 @@ poetry add -G dev \ - [axum]: asynchronous HTTP server framework - [color-eyre]: error report handler - [clap]: elegant CLI +- [chrono]: full-featured datetime library - [indicatif]: progress reporting +- [progenitor]: OpenAPI client generator - [reqwest]: asynchronous HTTP client - [serde]: serialization/deserialization framework - [seaorm]: async & dynamic ORM - [tokio]: asynchronous runtime - [tracing.rs]: a scoped, structured logging and diagnostics system +- [utoipa]: simple, fast, code first and compile time generated OpenAPI + documentation ## Shell @@ -225,7 +224,8 @@ poetry add -G dev \ ## Tooling -- [just]: General purpose task runner +- [just]: general purpose task runner +- [hyperfine]: benchmark compiled binaries ## Web @@ -255,14 +255,12 @@ Add the new `font-faces` to `styles/globals.css`: @font-face { font-family: "Dharma Gothic E"; - src: url("../public/fonts/Dharma Type - DharmaGothicE-ExBold.otf") - format("opentype"); + src: url("../public/fonts/Dharma Type - DharmaGothicE-ExBold.otf") format("opentype"); } @font-face { font-family: "Dharma Gothic E"; - src: url("../public/fonts/Dharma Type - DharmaGothicE-ExLight.otf") - format("opentype"); + src: url("../public/fonts/Dharma Type - DharmaGothicE-ExLight.otf") format("opentype"); } ``` @@ -298,6 +296,7 @@ Here are the components collection that have been selected by the team: [aiohttp]: https://docs.aiohttp.org/en/stable/ [clap]: https://clap.rs/ [color-eyre]: https://github.com/yaahc/color-eyre +[chrono]: https://github.com/chronotope/chrono [furo]: https://pradyunsg.me/furo [indicatif]: https://github.com/mitsuhiko/indicatif [invoke]: https://www.pyinvoke.org @@ -307,6 +306,7 @@ Here are the components collection that have been selected by the team: [myst-parser]: https://myst-parser.readthedocs.io/en/latest [next.js]: https://nextjs.org/docs [poetry]: https://python-poetry.org +[progenitor]: https://github.com/oxidecomputer/progenitor [pydantic]: https://pydantic-docs.helpmanual.io [pytest-cov]: https://github.com/pytest-dev/pytest-cov [pytest-mock]: https://github.com/pytest-dev/pytest-mock @@ -330,11 +330,14 @@ Here are the components collection that have been selected by the team: [tokio]: https://tokio.rs [typer]: https://typer.tiangolo.com [typescript]: https://www.typescriptlang.org +[uv]: https://docs.astral.sh/uv/ +[utoipa]: https://github.com/juhaku/utoipa [xdoctest]: https://github.com/Erotemic/xdoctest [just]: https://github.com/casey/just +[hyperfine]: https://github.com/sharkdp/hyperfine diff --git a/content/standards.md b/content/standards.md index b2b1cb9..7e1f229 100644 --- a/content/standards.md +++ b/content/standards.md @@ -83,9 +83,14 @@ and natural to build high quality deliverables. example of how to automate maintenance tasks. - Non trivial commands must be backed by scripts (instead of being written inline). -- Start designing API specification before implementation (i.e. design first +- Implement REST APIs from business requirements, and document them using the + [OpenAPI 3+ specification](https://swagger.io/specification/) (i.e. code first approach) - - Use the [OpenAPI 3+ specification](https://swagger.io/specification/) + - Generate the [OpenAPI 3+ specification] from the server + - Generate the clients from the [OpenAPI 3+ specification] for any language + needed. + - Clients must be 100% generated, although they might be **extended** if + needed. ### Continuous Integration @@ -159,8 +164,8 @@ type of work being done: Default: [MIT] -For most substantial [BNA Mechanics] open source software projects, there's a simple -default answer: [MIT]. +For most substantial [BNA Mechanics] open source software projects, there's a +simple default answer: [MIT]. [MIT] is the [most popular license](https://github.com/blog/1964-open-source-license-usage-on-github-com) @@ -422,7 +427,7 @@ Initialize the project, depending on the programming language: - Rust: `cargo init` - Python: - `poetry init --name "${PFB_REPO}" --description "${PFB_REPO_DESCRIPTION}"` + `uv init --name "${PFB_REPO}" --description "${PFB_REPO_DESCRIPTION}"` Add a `README.md` and the appropriate `.gitignore` file: @@ -513,8 +518,9 @@ gh repo archive -y [bna mechanics]: https://peopleforbikes.github.io [calver]: https://calver.org/ -[cc0-1.0]: https://choosealicense.com/licenses/cc0-1.0/ [cc-by-4.0]: https://creativecommons.org/licenses/by/4.0/deed.en +[cc0-1.0]: https://choosealicense.com/licenses/cc0-1.0/ [github]: http://github.com [mit]: https://choosealicense.com/licenses/mit/ +[openapi 3+ specification]: https://swagger.io/specification/ [the team]: mailto:research@peopleforbikes.org