Repo Structure and Public Repos#

In this section we want to give you a short insight into how we structure our repositories, and which common tools and scaffolds we use for (new) projects.

You will find all our public repositories on https://github.com/base-angewandte/. Here is a brief overview of what the different repos are used for:

  • base-docs: the repo for our entry-point documentation - the thing you are reading right now.

  • config: contains common configuration settings and generators for new project scaffolds.

  • pre-commit-hooks: contains all our pre-commit hooks, we use in backend projects for linting and streamlining code quality assurance. See Development Guide for details on how we code and commit.

  • nginx: contains the setup for running nginx as a reverse proxy for our actual applications.

  • base-ui-components: contains the all the common UI components that are used in our different frontend projects.

  • baseauth: a backend based on MamaCAS to provide authentication and user settings/preferences to other base applications.

  • portfolio-backend and portfolio-frontend: contains backend and frontend for the Portfolio application, to allow users manage their (scientific) portfolios.

  • showroom-backend and showroom-frontend: contains backend and frontend for the Showroom application, to showcase the (scientific) portfolios, users have entered (and published) on Portfolio.

Project/Repo specific documentation#

When you visit the repositories, they will provide either a README.md with setup instructions (in case of our frontends), or a docs/ folder similar to this documentation. Some of these are already rendered on readthedocs.io:

General backend repo structure#

  • The config directory contains our common base setup for linting, pre-commit hooks, and make commands. It is sourced from config repository as a git subtree. Depending on the use case of the specific repository, most of the files contained in this folder will be either copied or symlinked into the repository’s root folder. Here a few notes on these files:

    • .flake8, .hadolint.yaml, and .isort.cfg will usually be linked to, as they contain the linting configuration to adhere to our Coding conventions. No specific change on a repo basis should be needed.

    • .pre-commit-config.yaml and pyproject.toml will often be copied rather than be linked, particularly the pre-commit config, as most projects use different Python versions, and hence will need to reference different revision tags.

    • base.mk will be included in the project’s Makefile, and provides different make commands, one of which uses the make-gitignore.sh script to generate the .gitignore in the project’s root folder. The .gitignore in the config repo itself is just the most recent autogenerated version without any project-specific additions.

  • The docker folder contains all configs and setup for docker images used by an application.

  • The docs folder contains the actual documentation of a repository, where the index page is generated from the ./docs/source/index.rst file.

Makefile#

Every repository should contain a Makefile which contains at least the following:

include .env
export

# change this to the new project's name
# this will be used in config/base.mk, so check there if unsure how to name it
# for existing projects we e.g. use "baseauth", "portfolio", "showroom", or "nginx"
PROJECT_NAME ?= project-name

include config/base.mk

## add project specific targets below like in the example placeholder
.PHONY: placeholder
placeholder:  ## placeholder for demo purposes
    echo "This is just a placeholder for demo purposes"

Once this Makefile is created, make help can be used to list all available commands with a short note on what they do. Here a few notes on some of the targets and how to use them.

make gitignore#

This command is used to create the repo’s .gitignore file from a curated set of templates. This provides the minimal .gitignore we use in all our projects. If there are some project-specific additions needed, to ignore from git tracking, a .gitignore.local file can be used, which will be concatenated to the end of the .gitignore.

make %-default#

All our common make tartest, like e.g. make start can be overwritten project-specifically. The common targets are coded with a -default suffix (so actually make start will be a make start-default), and tab completion will suggest the -default-suffixed versions. But our base.mk adds a rule, that all -default-suffixed targets are available also without the suffix, unless this specific target ist already defined in the project’s Makefile.