From 3a80e1b3a35ee9e8f5cabc37283a0db03c2025a5 Mon Sep 17 00:00:00 2001 From: Gerasimos Chourdakis Date: Mon, 15 Jul 2024 20:41:51 +0200 Subject: [PATCH] Add dev docs page on naming conventions (#424) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add dev-docs-naming page * Update pages/docs/dev-docs/dev-naming.md Co-authored-by: Frédéric Simonis * Apply feedback from @BenjaminRodenberg --------- Co-authored-by: Frédéric Simonis --- _data/sidebars/docs_sidebar.yml | 4 ++ pages/docs/dev-docs/dev-naming.md | 61 +++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 pages/docs/dev-docs/dev-naming.md diff --git a/_data/sidebars/docs_sidebar.yml b/_data/sidebars/docs_sidebar.yml index b806347e54..98ff237424 100644 --- a/_data/sidebars/docs_sidebar.yml +++ b/_data/sidebars/docs_sidebar.yml @@ -580,6 +580,10 @@ entries: url: /dev-docs-overview.html output: web, pdf + - title: Naming + url: /dev-docs-naming.html + output: web, pdf + - title: Source documentation url: /dev-docs-sourcedocs.html output: web diff --git a/pages/docs/dev-docs/dev-naming.md b/pages/docs/dev-docs/dev-naming.md new file mode 100644 index 0000000000..c434f10d55 --- /dev/null +++ b/pages/docs/dev-docs/dev-naming.md @@ -0,0 +1,61 @@ +--- +title: Naming conventions +keywords: pages, development, naming +permalink: dev-docs-naming.html +summary: This page describes naming conventions for the preCICE ecosystem. +--- + +## The preCICE name + +preCICE is always stylized with lowercase `pre` and uppercase `CICE`, even in the beginning of a sentence. + +In technical contexts (e.g., a repository or package name), the lowercase `precice` is typically preferred. + +The forms `PreCICE` or `PRECICE` should be avoided, if possible. Hyphenating the name (e.g., `pre-CICE`) should be avoided. In LaTeX, use `\hyphenation{preCICE}`. + +## Naming adapters + +Wherever possible, adapters use composite names that start with the name of the code they adapt, followed by preCICE. For example, human-friendly names of adapters (e.g., appearing in a publication) are `FEniCS-preCICE` and `OpenFOAM-preCICE`. + +The motivation behind this is to be seen as extensions of the respective simulation code, and be easily discoverable in the context of that code. Looking at a package distribution repository, `fenicsprecice` should be close to `fenics`. + +The `adapter` is not part of the name, for concision reasons. The FEniCS community only wants to know that this package enables them to use preCICE with FEniCS. The "adapter" is preCICE-specific terminology. + +When hosted under the preCICE organization on GitHub, repositories are named as `fenics-adapter`, `openfoam-adapter`, etc. The names are always lowercase, and the dash increases readability. The `-adapter` part is now part of the name, because in the context of the preCICE organization on GitHub, the relevance to preCICE is implied: `precice/fenics-adapter`, `precice/openfoam-adapter`. + +## Naming tools + +preCICE-related tools that are meant to be started as executables should be prepended by `precice-`. For example: + +- `precice-tools` +- `precice-config-visualizer` +- `precice-micro-manager` +- `precice-aste` + +This allows easy auto-completion and grouping or related tools. + +As an exception, even if it is an executable developed in the context of preCICE, we consider the [fmiprecice](https://precice.org/tooling-fmi-runner.html) to follow the naming conventions of adapters, as it is seen from the perspective of the FMI community. + +## Python packages + +Packages on [PyPI](https://pypi.org/user/precice/) are named as follows: + +- `pyprecice`: The `py` implies this is the Python integration, as is common in the Python world (other examples: [`mpi4py`](https://mpi4py.readthedocs.io/en/stable/mpi4py.html), [`petsc4py`](https://petsc.org/main/petsc4py/reference/petsc4py.html), [`pyMOR`](https://pymor.org/)). We don't name it just `precice`, because it does not install preCICE itself. That could be a separate package in the future, which could be a dependency of `pyprecice`. Still, the package enables `import precice`: a Python version of the preCICE API. This is intended, as it is clear this is not the C++ API of preCICE. It is also shorter and more intuitive for the user. +- preCICE tools (names prepended by `precice-`): + - `precice-config-visualizer` + - `precice-config-visualizer-gui` + - `precice-micro-manager` (previously `micro-manager-precice`) +- preCICE adapters (names prepended by the respective code, the missing dash is consistent with the package name used with `import`): + - `fenicsprecice` + - `fmiprecice` + +## Docker images + +Images on [Docker Hub](https://hub.docker.com/u/precice) follow various names, which have not yet converged. + +Since images are always scoped by the user, the `precice-` is omitted from the name. For example: + +- `precice/precice` provides preCICE +- `precice/-bindings` provide language bindings on top of preCICE +- `precice/-precice` provide an adapter for a code +- `precice/ci-` do not provide preCICE, but dependencies and tools that are used to build preCICE in the CI