-
Notifications
You must be signed in to change notification settings - Fork 1
Repository Organization
This repository is a monorepo, meaning it houses multiple applications (microservices) that are independently versioned. However, to enable automated builds and the use of Protocol Buffers by external programs there is a Standard Operating Procedure for how the contents of this repository should be organized.
The top-level of the repository should only contain three things:
- Git/GitHub related content
- The global Protocol Buffer directory
- Microservice directories
This includes the following files:
root/
├── .github/
├── .gitignore
├── LICENSE
└── README.md
The .github/ directory contains GitHub specific content, such as the repository's CODE_OF_CONDUCT.md file and the GitHub Workflow that builds Docker container images when releases are tagged.
The .gitignore file is a top-level ignore file, i.e. microservice-specific files that should be ignored by git should go in the appropriate microservice directory's .gitignore file, not the top-level .gitignore file.
The LICENSE file contains the software license under which all contents of the repository are bound. It is recommended that individual microservices also contain a copy of this license to be distributed with the microservice when they are built.
Normalizing data types across microservices is encouraged. As such, any data type a microservice that supports gRPC uses (other than service specific messages) should be defined in global Protocol Buffer files, i.e. they are "owned" by the repository and independently versioned, rather than being tied to any one microserrvice. All such Protocol Buffers should be put in the top-level proto/ directory:
root/
└── proto/
See the Protocol Buffers page for more information on how the contents of the proto/ directory should be organized and used, and see the Tagging Releases and Automated Builds page for more information on how Protocol Buffers should be versioned.
Each microservice should be contained in its own top-level directory. The name of a microservice's directory should conform to the standards of the language it is implemented in. For example, microservices impllemented in Python should use the PEP 8 package naming convention - all lowercase with optional underscores:
root/
├── <microservice_1>/
├── <microservice_2>/
├── ...
└── <microservice_n>/
The top-level of each microservice directory should contain three things:
- A Dockerfile
- A readme file
- Git/GitHub related content
Additionally, if the microservice supports gRPC, then it must also contain:
- A Protocol Buffer directory
Specifically, a microservice should have the following top-level file structure:
root/
└── <microservice>/
├── proto/
├── .gitignore
├── Dockerfile
├── LICENSE
└── README.md
The README.md file is required and should explain what the microservice does and how to install and run it.
The Dockerfile file is also required. At a minimum, this should build a container image for use in production. It is encouraged to use a multi-stage build that also provides a container image for development. See the Tagging Releases and Automated Builds page for information on how to automate building and publishing the container images defined in this file.
The .gitignore file is not required but should be used to specify any files specific to the microservice that should be ignored by git.
The LICENSE file is also not required. If it is included, it should be a copy of the LICENSE file at the top-level of the repository.
The proto/ directory is only required if the microservice supports gRPC. It should contain the Protocol Buffers that define the service's gRPC messages and copies of any global Protocol Buffers that define data types the service uses. See the Protocol Buffers page for information on how these files should be organized and how global Protocol Buffers should be copied into microservice directories in a version controlled manner.