copier.yml

---
project_name:
  type: str
  help: >
    Name of the project and generated extensions
    (don't include `saltext-` prefix)
  placeholder: vault
  validator: >-
    {%- if not project_name %}
    Project name cannot be empty.
    {%- endif %}
    {%- if not (project_name | regex_search("^[a-z][a-z0-9\\-]+$")) %}
    Must start with [a-z], followed by at least one of [a-z0-9\-] (lowercase!)
    {%- endif %}

author:
  type: str
  help: Author for project metadata
  placeholder: Elliot Alderson
  validator: '{%- if not author %}Author cannot be empty{%- endif %}'

author_email:
  type: str
  help: The author's contact email address
  placeholder: elliotalderson@protonmail.ch
  validator: >-
    {%- if not author_email -%}Email cannot be empty
    {%- elif not author_email | regex_search("[\\S]+@[^\\.\\s]+") -%}
    Does not look like a valid email address
    {%- endif -%}

integration_name:
  type: str
  help: >
    The full name of the integrated service. If this extension does not
    integrate one, just leave this empty.
  placeholder: HashiCorp Vault
  default: '{{ project_name.replace("-", " ").title() }}'

summary:
  type: str
  help: A summary for project metadata and the readme
  default: >-
    Salt Extension for interacting with
    {{ integration_name or project_name.replace("-", " ").title() }}

url:
  type: str
  help: The project's homepage (usually the URL of the hosted repo)
  default: https://github.com/salt-extensions/saltext-{{ project_name }}
  validator: '{%- if not url %}URL cannot be empty{%- endif %}'

source_url:
  type: str
  help: The project's repo URL
  default: >-
    {%- if "github.com" in url -%}
      {{ url }}
    {%- else -%}
      https://github.com/salt-extensions/saltext-{{ project_name }}
    {%- endif %}
  validator: >-
    {%- if "://" not in source_url -%}Does not look like a valid URL
    {%- endif %}

tracker_url:
  type: str
  help: The project's issue tracker URL
  default: >-
    {%- if "github.com" in source_url -%}
      {{ source_url }}/issues
    {%- endif -%}
  validator: >-
    {%- if tracker_url and "://" not in tracker_url -%}Does not look like a valid URL
    {%- endif %}

package_name:
  type: str
  help: The name of the Python package (without `saltext.` prefix)
  default: '{{ project_name | regex_replace("[-_.]+", "_") }}'
  validator: >-
    {%- if not package_name %}
    Package name cannot be empty.
    {%- endif %}
    {%- if not (package_name | regex_search("^[a-z][a-z0-9_]+$")) %}
    Must start with [a-z], followed by at least one of [a-z0-9_] (lowercase!)
    {%- endif %}

license:
  type: str
  help: Choose a license for the project
  default: apache
  choices:
    - apache
    - other

license_classifier:
  type: str
  help: The classifier for {{ license }}. See https://pypi.org/classifiers.
  when: '{{ license != "apache" }}'
  default: '{%- if license == "apache" %}License :: OSI Approved :: Apache Software License{%- endif %}'
  placeholder: '{%- if license != "apache" %}License :: OSI Approved :: Apache Software License{%- endif %}'
  validator: '{%- if " :: " not in license_classifier %}Invalid license classifier{%- endif %}'

license_name:
  type: str
  when: false
  default: '{{ license_classifier.split(" :: ") | last }}'

loaders:
  type: str
  help: Which module types should be implemented
  default:
    - module
    - state
  choices:
    - auth
    - beacon
    - cache
    - cloud
    - engine
    - executor
    - fileserver
    - grain
    - log_handler
    - matcher
    - metaproxy
    - module
    - netapi
    - output
    - pillar
    - pkgdb
    - pkgfile
    - proxy
    - queue
    - renderer
    - returner
    - roster
    - runner
    - sdb
    - serializer
    - state
    - thorium
    - token
    - top
    - wheel
    - wrapper
  multiselect: true

salt_version:
  type: str
  help: Minimum Salt version to support
  default: '3006'
  validator: >-
    {%- import "data/salt_python_support.yaml" as sps -%}
    {%- set sup = sps | string | from_yaml -%}
    {%- if salt_version | float | int not in sup -%}
      Unknown Salt version. Known major: {{ sup | join(", ") }}
    {%- endif -%}
    {%- if "." in salt_version -%}
    {%-   if salt_version.count(".") > 1 -%}
      Unknown Salt version format. Allowed: MAJOR, MAJOR.MINOR
    {%-   else -%}
    {%-     import "data/salt_latest_point.yaml" as spr -%}
    {%-     set slp = spr | string | from_yaml -%}
    {%-     set major, minor = salt_version.split(".") | map("int") -%}
    {%-     if slp[major] < minor -%}
      Unknown minor release. Latest known: {{ major }}.{{ slp[major] }}
    {%-     endif -%}
    {%-   endif -%}
    {%- endif -%}

python_requires:
  type: str
  help: Minimum Python version to support
  default: >-
    {%- import "data/salt_python_support.yaml" as sps -%}
    {%- set sup = sps | string | from_yaml -%}
    {{- sup[salt_version | float | int]["min"] | join(".") -}}
  validator: >-
    {%- import "data/salt_python_support.yaml" as sps -%}
    {%- set sup = sps | string | from_yaml -%}
    {%- set minsup = sup[salt_version | float | int]["min"] -%}
    {%- set selected = python_requires.split(".") | map("int") | list -%}
    {%- if selected < minsup -%}
    Minimum supported Python version of Salt {{ salt_version }} is {{ minsup | join(".") }}
    {%- endif -%}

max_salt_version:
  type: str
  help: The maximum Salt major version to support
  default: '3007'
  validator: >-
    {%- import "data/salt_python_support.yaml" as sps -%}
    {%- set sup = sps | string | from_yaml -%}
    {%- if max_salt_version | float | int not in sup -%}
      Unknown Salt version. Known major: {{ sup | join(", ") }}
    {%- endif -%}
    {%- if "." in max_salt_version -%}
    {%-   if max_salt_version.count(".") > 1 -%}
      Unknown Salt version format. Allowed: MAJOR, MAJOR.MINOR
    {%-   else -%}
    {%-     import "data/salt_latest_point.yaml" as spr -%}
    {%-     set slp = spr | string | from_yaml -%}
    {%-     set major, minor = max_salt_version.split(".") | map("int") -%}
    {%-     if slp[major] < minor -%}
      Unknown minor release. Latest known: {{ major }}.{{ slp[major] }}
    {%-     endif -%}
    {%-   endif -%}
    {%- endif -%}
    {%- if (max_salt_version | float) < (salt_version | float) -%}
      Maximum version needs to be at least {{ salt_version }}
    {%- endif -%}

no_saltext_namespace:
  type: bool
  help: Omit the `saltext` namespace
  default: false

ssh_fixtures:
  type: bool
  help: Generate pytest fixtures for salt-ssh
  default: '{{ "wrapper" in loaders }}'
  when: '{{ "wrapper" not in loaders }}'

test_containers:
  type: bool
  help: Add support for test containers in functional/integration tests
  default: false

os_support:
  type: str
  multiselect: true
  help: Supported OS. Influences where tests run.
  default:
    - Linux
    - macOS
    - Windows
  choices:
    - Linux
    - macOS
    - Windows
  validator: >-
    {%- if not os_support -%}
      At least one supported OS is required.
    {%- endif -%}

deploy_docs:
  type: str
  help: >-
    When to automatically deploy CI built docs to GitHub Pages.
    Does not support versioned docs currently.
    Requires Settings > Pages > Build and deployment source to be `GitHub Actions`.
  default: '{{ "rolling" if "github.com/salt-extensions/" in source_url else "never" }}'
  choices:
    never: never
    when tagging a release: release
    all events on `main` (rolling): rolling
  when: '{{ "github.com" in source_url }}'

docs_url:
  type: str
  help: The project's documentation URL (optional)
  default: >-
    {%- if deploy_docs != "never" -%}
      {%- set repo_parts = source_url.split("github.com/")[1].split("/") -%}
      {{- "https://{}.github.io/{}/".format(repo_parts[0], repo_parts[1]) -}}
    {%- endif -%}
  validator: >-
    {%- if docs_url and "://" not in docs_url -%}Does not look like a valid URL
    {%- endif %}

coc_contact:
  type: str
  help: Optionally provide a contact for Code of Conduct violation reports.
  default: ''

copyright_begin:
  help: Copyright range beginning year
  type: int
  default: '{{ "%Y" | strftime }}'
  # Cannot use when: false to set this once automatically during
  # creation since the value is not recorded then.

relax_pylint:
  type: bool
  help: Suppress some Pylint messages that can cause noise or be difficult to solve with legacy code.
  default: false

# ===========================================
# | Computed values for less ugly templates |
# ===========================================

package_namespace:
  type: str
  when: false
  default: '{%- if not no_saltext_namespace %}saltext{%- endif %}'

package_namespace_pkg:
  type: str
  when: false
  default: '{%- if package_namespace %}{{ package_namespace }}.{%- endif %}'

package_namespace_path:
  type: str
  when: false
  default: '{%- if package_namespace %}{{ package_namespace }}/{%- endif %}'

namespaced_package_path:
  type: str
  when: false
  default: '{{ package_namespace_path ~ package_name }}'

namespaced_package_pkg:
  type: str
  when: false
  default: '{{ package_namespace_pkg ~ package_name }}'

project_name_full:
  type: str
  when: false
  default: >-
    {%- if package_namespace %}
    {{- package_namespace }}-{{ project_name }}
    {%- else %}
    {{- project_name }}
    {%- endif %}

# In theory, both Salt version bounds can be specified with a minor qualifier.
# We might need major and minor separately in the template, so pre-comute them.
# If no minor was specified, default to the latest known minor release.
salt_version_major:
  type: int
  when: false
  default: '{{ salt_version | float | int }}'

salt_version_minor:
  type: int
  when: false
  default: >-
    {%- if "." in salt_version -%}
      {{- salt_version.split(".") | last -}}
    {%- else -%}
      {%- import "data/salt_latest_point.yaml" as spr -%}
      {%- set slp = spr | string | from_yaml -%}
      {{- slp[salt_version_major] -}}
    {%- endif -%}

max_salt_version_major:
  type: int
  when: false
  default: '{{ max_salt_version | float | int }}'

max_salt_version_minor:
  type: int
  when: false
  default: >-
    {%- if "." in max_salt_version -%}
      {{- max_salt_version.split(".") | last -}}
    {%- else -%}
      {%- import "data/salt_latest_point.yaml" as spr -%}
      {%- set slp = spr | string | from_yaml -%}
      {{- slp[max_salt_version_major] -}}
    {%- endif -%}

max_python_minor:
  type: int
  when: false
  default: >-
    {%- import "data/salt_python_support.yaml" as sps -%}
    {%- set sup = sps | string | from_yaml -%}
    {{- sup[max_salt_version_major]["max"][1] -}}

# ========================================
# | Migrations between template versions |
# ========================================

_migrations:
  # All general migrations are handled inside this script, which runs in both before and after stages.
  - command: >-
      "{{ _copier_python }}"
      "{{ "{src}{sep}tasks{sep}migrations.py".format(src=_copier_conf.src_path, sep=_copier_conf.sep) }}"
    when: 'true'
  # (Re)initialize the project and run pre-commit after updating
  - >-
    "{{ _copier_python }}"
    "{{ "{src}{sep}tasks{sep}initialize.py".format(src=_copier_conf.src_path, sep=_copier_conf.sep) }}"
    migrate

_tasks:
  # Don't run this when updating (updating copies the template twice).
  # This breaks when recopying.
  # We should be able to simplify this check in the future to:
  # if _copier_conf.operation == "copy".
  - >-
    {%- if
      not _copier_conf.answers.last
      and '.new_copy.' not in _copier_conf.dst_path.name
      and '.old_copy.' not in _copier_conf.dst_path.name -%}
        "{{ _copier_python }}" "{{ "{src}{sep}tasks{sep}initialize.py".format(src=_copier_conf.src_path, sep=_copier_conf.sep) }}" init
    {%- endif -%}

# =====================================
# | Copier settings for this template |
# =====================================

# We need the new migration syntax
_min_copier_version: "9.3.0"

# The template root is found here
_subdirectory: project

# Don't offer updates to implementation-specific files
_skip_if_exists:
  - tests/**/test_*.py
  - src/**/*_mod.py

# Ensure we're compatible with the official tool
_templates_suffix: j2

# We need those extensions as helpers
_jinja_extensions:
  - copier_templates_extensions.TemplateExtensionLoader
  - jinja_extensions/saltext.py:YamlDumper
  - jinja_extensions/saltext.py:SaltExt
  - jinja2.ext.do
  - jinja2.ext.loopcontrols

# Before initialization, describe briefly what this is about
_message_before_copy: |

  Welcome to salt-extension-copier!

  Even after generation, this template can be used to perform
  updates to your project's boilerplate.


  Anything unclear? Visit the comprehensive user documentation:

    ▶ https://salt-extensions.github.io/salt-extension-copier/

# Describe next steps and rough usage after project initialization
_message_after_copy: |

  Your Salt extension project "{{ project_name_full }}" has been created successfully! 🎉

  At this point, your development environment should be ready to go.
  If you have installed `direnv`, it can be activated automatically,
  otherwise you need to source the Python virtual environment manually:

    $ cd '{{ _copier_conf.dst_path }}'
    $ source .venv/bin/activate

  If you encounter any problems, try the manual steps documented here:

    ▶ https://salt-extensions.github.io/salt-extension-copier/topics/creation.html#first-steps

  {%- if "github.com/salt-extensions/" in source_url %}

  Once you're ready, submit a repository request to the organization:

    ▶ https://salt-extensions.github.io/salt-extension-copier/topics/organization/submitting.html
  {%- endif %}


  Please update the tests :) Happy hacking!