Contributing

Prepare Development Environment

  • Prepare dev tools:
    • Install GIT
    • Install Git Flow
    • Install Python, PIP, Virtual Environment Wrapper
  • Clone GIT repositories
# Create the main repository
cd <YOUR_PROJECTS_PATH>
git clone https://github.com/serdigital64/aplatform64
cd aplatform64
# Create module repositories as git submodules
git submodule init
# Update modules
git submodule update
# Enable main branch on submodules
git submodule foreach "git checkout main"; git submodule foreach "git checkout develop"
# (Optional) Initialize git flow. Production branch:main, use defaults for the remaining branches
git submodule foreach "git flow init"
  • Adjust environment variables to reflect your configuration:
# Copy environment definition files from templates:
cp dot.local .local
cp dot.secrets .secrets
# Review and update content for both files
  • Create Python Virtual Environment Wrapper workspace
source .local
source .env
source "$DEVAP_VEW_LOADER"
mkvirtualenv aplatform64
  • Install Python dev modules
pip3 install --upgrade -r requirements-aplatform64.txt
  • The environment is now ready. From now use the following script to load environment variables and set the virtual Python environment:
source bin/devap-set
  • Download the latest version of BashLib64 to: lib/

Update source code

  • CLI:
    • Add/Edit source code in: src/cli
  • Collections
    • Work on the collection repository using it's own development branch

Design principles

Role Structure

Defaults
  • Used as an interface to expose role end-state attributes and action parameters

    Path Purpose
    defaults/ Root directory where Ansible will look for defaults
    defaults/main/ Allow Ansible to use individual default definition files instead of a single main.yml entry point
    defaults/main/end_state_definition.yml Declare what are the end-state attributes that the role will set.
    defaults/main/action_parameters.yml Declare what parameters are available to define how role actions will behave.
  • All role attributes and parameters must be declared. If the variable doesn't have a default value then it must be initialized to the empty value associated to the variable type (number, string, dictionary, list)
  • Complex variables (dictionaries, lists) must be further documented in the vars/dictionary.yml file
  • State definition attributes are permanent and are intended to represent the desired state. Non-default values must be defined as host_variables or group_variables and are the main component for implementing the infrastructure-as-code strategy
  • Action parameter variables are dynamic and are reset every time the role is executed. This allows common roles to be executed several times without inheriting default settings from previous iterations.
Actions
Action: Prepare
  • Purpose: prepare the role runtime environment.
  • Common tasks:
    • Create users.
    • Create directory structures.
Action: Deploy
  • Purpose: install application packages used by the role.
  • Common tasks:
    • Install native operating system application packages.
    • Install application packages distributed as single archives.
    • Install application packages from GIT.
    • Install application packages from Snap.
    • Install application packages from FlatHub.
Action: Setup
  • Purpose: setup configuration files used by the role.
  • Common tasks:
    • Create configuration files
    • Update configuration files
Action: Control
  • Purpose: control the execution of services managed by the role.
  • Common tasks:
    • Star/Stop the service.
    • Refresh/Reload the service.
Action: Provision
  • Purpose: perform provisioning tasks for content managed by the role.
  • Common tasks: tasks are dependant on the role.

Code Templates

Use the following code templates from the project CodeSkel64 for adding content to the project:

Versioning Strategy

Branching Model

Change Log Format

Linting

  • Global Ansible Lint definition: $DEVAP_ROOT/.ansible-lint
  • Global YAML Lint definition: $DEVAP_ROOT/.yamllint
  • Global ShellCheck Lint definition: $DEVAP_ROOT/.shellcheckrc

Test source code

  • Build Collection packages:
bin/devap-build -t
  • Run molecule tests:
./bin/devap-test

Documentation

  • Documentation is created using MkDocs and published in the https://readthedocs.org/] site.
  • Each collecttion and role has it's own document (README.md)

Commit Message Strategy

  • Conventional Commits
  • Subject Format: Type: Summary
  • Subject Max Length: 50 characters
  • Types:
    • build
    • docs
    • feat
    • fix
    • refactor
    • style
    • test
  • Summary Templates:
    • update xxx
    • remove xxx
    • fix xxx
    • set initial structure

Naming Convention

  • Collections
    • definition: represents a technology or service
    • lowercase
    • single word
  • Roles
    • definition: represents a component of the technology managed by the collection
    • lowercase
    • words separate by _
    • combined word: collection name + role name
    • template: collection_role
  • Tasks
    • definition: represents a set of actions
    • lowercase
    • words separate by _
    • combined word: collection name + role name + task name + subtask name
    • templates
      • collection_role_task.yml
      • collection_role_task_subtask.yml
  • Defaults
    • main/state_definition.yml
    • main/action_parameters.yml
  • Variables
    • lowercase
    • words separate by _
    • combined word: collection name + role name + variable name
    • templates
      • collection_role_variable
      • collection_role___temporary_variable

Repositories