Update standards and guidelines (#47)

Signed-off-by: Rémy Greinhofer <[email protected]>

Author: rgreinho

.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
 

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
 

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:

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
 
 <!-- Tooling -->
 
 [just]: https://github.com/casey/just
+[hyperfine]: https://github.com/sharkdp/hyperfine
 
 <!-- General links -->
 

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:[email protected]