From 8408d499156adc5bce474f4adbd7ee1f227ed572 Mon Sep 17 00:00:00 2001 From: KerstenBreuer Date: Wed, 20 Dec 2023 13:40:13 +0000 Subject: [PATCH] add a template description (GSI-545) Is only present on the template and automatically removed for relying service repos. --- .readme_generation/description.md | 25 +---------- .readme_generation/readme_template.md | 4 +- .readme_generation/template_overview.md | 27 ++++++++++++ README.md | 57 ++++++++++++++----------- scripts/update_readme.py | 22 +++++++++- 5 files changed, 81 insertions(+), 54 deletions(-) create mode 100644 .readme_generation/template_overview.md diff --git a/.readme_generation/description.md b/.readme_generation/description.md index ef8eb2b2..2ad6dc4f 100644 --- a/.readme_generation/description.md +++ b/.readme_generation/description.md @@ -1,26 +1,3 @@ -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. diff --git a/.readme_generation/readme_template.md b/.readme_generation/readme_template.md index 10e3e612..47e42074 100644 --- a/.readme_generation/readme_template.md +++ b/.readme_generation/readme_template.md @@ -1,6 +1,6 @@ -[![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 diff --git a/.readme_generation/template_overview.md b/.readme_generation/template_overview.md new file mode 100644 index 00000000..6e148ef3 --- /dev/null +++ b/.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: + +--- diff --git a/README.md b/README.md index 3238efd4..ff8cb9e5 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,59 @@ +# Microservice Repository Template -[![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) +This is a template for GitHub repositories containing one Python-based microservice (optimal for a multirepository setup). -# Microservice Repository Template +It features: -My-Microservice - a short description +- *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 -## Description +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. -This repo is a template for creating a new microservice. +Here the intro to the template stops and the actual template for the readme of the microservice starts: -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` +[![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. + -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, @@ -56,7 +61,7 @@ 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: diff --git a/scripts/update_readme.py b/scripts/update_readme.py index c0dd4e32..b8273b02 100755 --- a/scripts/update_readme.py +++ b/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.")