add a template description (GSI-545) (#188)

Is only present on the template and automatically removed for relying service repos.

.readme_generation/description.md

@@ -1,26 +1,3 @@
 <!-- Please provide a short overview of the features of this service. -->
 
-This repo is a template for creating a new microservice.
-
-The directories, files, and their structure herein are recommendations
-from the GHGA Dev Team.
-
-### Naming Conventions
-
-The GitHub repository contains only lowercase letters, numbers, and hyphens "-",
-e.g.: `my-microservice`
-
-The Python package (and thus the source repository) contains underscores "_"
-instead of hyphens, e.g.: `my_microservice`
-However, an abbreviated version is prefered as package name.
-
-### Adapt to your service
-
-This is just a template and needs some adaptation to your specific use case.
-
-Please search for **"please adapt"** comments. They will indicate all locations that
-need modification. Once the adaptations are in place, please remove these comments.
-
-Finally, follow the instructions to generate the README.md described in
-[`./readme_generation.md`](./readme_generation.md). Please also adapt this markdown file
-by providing an overview of the feature of the package.
+Here you should provide a short summary of the purpose of this microservice.

.readme_generation/readme_template.md

@@ -1,6 +1,5 @@
-
-[![tests](https://github.com/ghga-de/$name/actions/workflows/tests.yaml/badge.svg)](https://github.com/ghga-de/$name/actions/workflows/tests.yaml)
-[![Coverage Status](https://coveralls.io/repos/github/ghga-de/$name/badge.svg?branch=main)](https://coveralls.io/github/ghga-de/$name?branch=main)
+[![tests](https://github.com/ghga-de/$repo_name/actions/workflows/tests.yaml/badge.svg)](https://github.com/ghga-de/$repo_name/actions/workflows/tests.yaml)
+[![Coverage Status](https://coveralls.io/repos/github/ghga-de/$repo_name/badge.svg?branch=main)](https://coveralls.io/github/ghga-de/$repo_name?branch=main)
 
 # $title
 

.readme_generation/template_overview.md

@@ -0,0 +1,27 @@
+# Microservice Repository Template
+
+This is a template for GitHub repositories containing one Python-based microservice (optimal for a multirepository setup).
+
+It features:
+
+- *Continuous Templation* - A continuous update-delivery mechanism for templated repositories
+- A [devcontainer](https://containers.dev/)-based fully-configured development environment for vscode
+- Tight linting and formatting using [Ruff](https://docs.astral.sh/ruff/)
+- Static type checking using [mypy](https://www.mypy-lang.org/)
+- Security scanning using [bandit](https://bandit.readthedocs.io/en/latest/)
+- A structure for automated tests using [pytest](https://docs.pytest.org/en/7.4.x/)
+- Dependency locking using [pip-tools](https://github.com/jazzband/pip-tools)
+- Git hooks checking linting and formatting before committing using [pre-commit](https://pre-commit.com/)
+- Automatic container-building and publishing to [Docker Hub](https://hub.docker.com/)
+- GitHub Actions for automating or checking all of the above
+
+It is worth emphasizing the first point, this template is not just a one-time kickstart for your project
+but repositories created using this template will continue receiving updates as the template evolves.
+For further details, please look at the explanation in [.template/README.md](/.template/README.md).
+
+Please also refer to [.readme_generation/README.md](/.readme_generation/README.md) for details on how
+to adapt this readme.
+
+Here the intro to the template stops and the actual template for the readme of the microservice starts:
+
+---

README.md

@@ -1,62 +1,65 @@
-
-[![tests](https://github.com/ghga-de/microservice-repository-template/actions/workflows/tests.yaml/badge.svg)](https://github.com/ghga-de/microservice-repository-template/actions/workflows/tests.yaml)
-[![Coverage Status](https://coveralls.io/repos/github/ghga-de/microservice-repository-template/badge.svg?branch=main)](https://coveralls.io/github/ghga-de/microservice-repository-template?branch=main)
-
 # Microservice Repository Template
 
-My-Microservice - a short description
+This is a template for GitHub repositories containing one Python-based microservice (optimal for a multirepository setup).
 
-## Description
+It features:
 
-<!-- Please provide a short overview of the features of this service. -->
+- *Continuous Templation* - A continuous update-delivery mechanism for templated repositories
+- A [devcontainer](https://containers.dev/)-based fully-configured development environment for vscode
+- Tight linting and formatting using [Ruff](https://docs.astral.sh/ruff/)
+- Static type checking using [mypy](https://www.mypy-lang.org/)
+- Security scanning using [bandit](https://bandit.readthedocs.io/en/latest/)
+- A structure for automated tests using [pytest](https://docs.pytest.org/en/7.4.x/)
+- Dependency locking using [pip-tools](https://github.com/jazzband/pip-tools)
+- Git hooks checking linting and formatting before committing using [pre-commit](https://pre-commit.com/)
+- Automatic container-building and publishing to [Docker Hub](https://hub.docker.com/)
+- GitHub Actions for automating or checking all of the above
 
-This repo is a template for creating a new microservice.
+It is worth emphasizing the first point, this template is not just a one-time kickstart for your project
+but repositories created using this template will continue receiving updates as the template evolves.
+For further details, please look at the explanation in [.template/README.md](/.template/README.md).
 
-The directories, files, and their structure herein are recommendations
-from the GHGA Dev Team.
+Please also refer to [.readme_generation/README.md](/.readme_generation/README.md) for details on how
+to adapt this readme.
 
-### Naming Conventions
+Here the intro to the template stops and the actual template for the readme of the microservice starts:
 
-The GitHub repository contains only lowercase letters, numbers, and hyphens "-",
-e.g.: `my-microservice`
+---
+[![tests](https://github.com/ghga-de/microservice-repository-template/actions/workflows/tests.yaml/badge.svg)](https://github.com/ghga-de/microservice-repository-template/actions/workflows/tests.yaml)
+[![Coverage Status](https://coveralls.io/repos/github/ghga-de/microservice-repository-template/badge.svg?branch=main)](https://coveralls.io/github/ghga-de/microservice-repository-template?branch=main)
 
-The Python package (and thus the source repository) contains underscores "_"
-instead of hyphens, e.g.: `my_microservice`
-However, an abbreviated version is prefered as package name.
+# My Microservice
 
-### Adapt to your service
+My-Microservice - a short description
 
-This is just a template and needs some adaptation to your specific use case.
+## Description
 
-Please search for **"please adapt"** comments. They will indicate all locations that
-need modification. Once the adaptations are in place, please remove these comments.
+<!-- Please provide a short overview of the features of this service. -->
 
-Finally, follow the instructions to generate the README.md described in
-[`./readme_generation.md`](./readme_generation.md). Please also adapt this markdown file
-by providing an overview of the feature of the package.
+Here you should provide a short summary of the purpose of this microservice.
 
 
 ## Installation
 
 We recommend using the provided Docker container.
 
-A pre-build version is available at [docker hub](https://hub.docker.com/repository/docker/ghga/microservice-repository-template):
+A pre-build version is available at [docker hub](https://hub.docker.com/repository/docker/ghga/my-microservice):
 ```bash
-docker pull ghga/microservice-repository-template:0.1.0
+docker pull ghga/my-microservice:0.1.0
 ```
 
 Or you can build the container yourself from the [`./Dockerfile`](./Dockerfile):
 ```bash
 # Execute in the repo's root dir:
-docker build -t ghga/microservice-repository-template:0.1.0 .
+docker build -t ghga/my-microservice:0.1.0 .
 ```
 
 For production-ready deployment, we recommend using Kubernetes, however,
 for simple use cases, you could execute the service using docker
 on a single server:
 ```bash
 # The entrypoint is preconfigured:
-docker run -p 8080:8080 ghga/microservice-repository-template:0.1.0 --help
+docker run -p 8080:8080 ghga/my-microservice:0.1.0 --help
 ```
 
 If you prefer not to use containers, you may install the service from source:

scripts/update_readme.py

@@ -33,6 +33,7 @@
 ROOT_DIR = Path(__file__).parent.parent.resolve()
 PYPROJECT_TOML_PATH = ROOT_DIR / "pyproject.toml"
 README_GENERATION_DIR = ROOT_DIR / ".readme_generation"
+TEMPLATE_OVERVIEW_PATH = README_GENERATION_DIR / "template_overview.md"
 DESCRIPTION_PATH = README_GENERATION_DIR / "description.md"
 DESIGN_PATH = README_GENERATION_DIR / "design.md"
 README_TEMPLATE_PATH = README_GENERATION_DIR / "readme_template.md"
@@ -59,6 +60,7 @@ class PackageHeader(BaseModel):
 class PackageName(BaseModel):
     """The name of a package and it's different representations."""
 
+    repo_name: str = Field(..., description="The name of the repo")
     name: str = Field(..., description="The full name of the package in spinal case.")
     title: str = Field(..., description="The name of the package formatted as title.")
 
@@ -119,9 +121,21 @@ def read_package_name() -> PackageName:
         raise RuntimeError("The name of the git origin could not be resolved.")
     git_origin_name = stdout.decode("utf-8").strip()
 
-    return PackageName(
-        name=spinalcase(git_origin_name), title=titlecase(git_origin_name)
+    repo_name = spinalcase(git_origin_name)
+    name = (
+        "my-microservice"
+        if repo_name == "microservice-repository-template"
+        else repo_name
     )
+    title = titlecase(name)
+
+    return PackageName(repo_name=repo_name, name=name, title=title)
+
+
+def read_template_overview() -> str:
+    """Read the template_overview."""
+
+    return TEMPLATE_OVERVIEW_PATH.read_text()
 
 
 def read_package_description() -> str:
@@ -205,6 +219,10 @@ def main(check: bool = False) -> None:
     details = get_package_details()
     readme_content = generate_single_readme(details=details)
 
+    if details.repo_name == "microservice-repository-template":
+        template_overview = read_template_overview()
+        readme_content = template_overview + readme_content
+
     if check:
         if README_PATH.read_text() != readme_content:
             echo_failure("README.md is not up to date.")