Sombra File

The Sombra File (sombra.yaml) is a core configuration file used within the target repositories that are generated using Sombra Templates. It contains crucial information such as project metadata, configuration settings, and variables that are used to make each project unique.

Structure

A typical Sombra File is written in YAML and consists of key sections that define metadata and customizable settings for the generated project:

Branch (branch): Specifies the branch that should be used for the project setup. This allows you to control which version of a template is used when generating the project.
```
branch: sombra-app-template-install  # Branch name to use for the template
```

Templates (templates): Defines the templates that will be used for generating the project. This section can include multiple templates, each with its own set of variables to customize the output.

templates:
  - name: cool-org/playground-django-api-template
    vars:
      project: Awesome Project           # Define the project name
      author: Alex Smith                 # Define the author's name
      email: alex.smith@example.com      # Define the author's email
      entity: Settings                   # Define the entity name

Key Elements

Branch Specification: The branch field defines which branch of the template repository will be used to generate the project, providing flexibility for testing and version management.
Template Customization: The templates section allows users to specify multiple templates and define variables for each, making it easy to adapt the project to different use cases.
Custom Variables: Define variables that are unique to each generated project. These can be easily filled in to personalize the generated project and ensure that it matches user requirements.

Example Sombra File

Below is an example of a simple Sombra File (sombra.yaml) that could be used in a target repository to provide project-specific values:

branch: sombra-app-template-install  # Branch to be used for template generation

templates:
  - name: cool-org/playground-django-api-template
    vars:
      project: My Awesome Project        # Define the project name
      author: Jane Doe                   # Define the author's name
      email: jane.doe@example.com        # Define the author's email
      entity: Settings                   # Define the entity name

This example illustrates how the Sombra File can be used to define the branch, choose a template, and store key metadata and configurations, allowing each generated project to be tailored easily based on user-defined input.

Conclusion

The Sombra File (sombra.yaml) is a powerful tool for customizing projects generated using Sombra templates. By defining branches, selecting templates, and specifying project-specific variables, developers can generate projects that are highly customized while maintaining consistency and keeping templates reusable. Understanding and utilizing the Sombra File effectively is crucial for achieving flexibility and maintainability in your projects.