Skip to content

Meta-Level Documentation: Git Development and Deployment Workflows

Overview

This document provides a meta-level analysis of the Git-based development and deployment workflows used in the repository. The goal is to align these workflows conceptually and technically while identifying gaps and ensuring consistency.

Core Workflows

1. Development Workflow

Purpose

  • Supports feature development, bug fixes, and other contributions using a branch-based workflow.

Key Components

  • Branches:
  • main: Stable release branch.
  • staging: Active development branch for integration testing.
  • Feature branches: For specific tasks or issues.
  • Commits: Follow conventional commit messages to ensure clarity.
  • Pull Requests (PRs): Used to merge feature branches into staging.

Tools and Actions

  • Git CLI for branch management.
  • Automated checks triggered by PR events (e.g., linting, testing).

Known Issues

  • Need for clearer branch naming conventions.
  • Standardization of commit message format.

Gaps and Recommendations

  • Document branch naming conventions explicitly.
  • Integrate a commit linter to enforce standards.

2. Release Management Workflow

Purpose

  • Manages the preparation, validation, and deployment of new releases.

Key Components

  • Tagging:
  • Pre-release tags: prep-vX.Y.Z to trigger workflows.
  • Final release tags: vX.Y.Z for stable releases.
  • Changelog Updates: Automated updates during release preparation.
  • Release Branches: Created during the preparation of major or minor versions.

Tools and Actions

  • Release Drafter: Generates draft release notes based on merged PRs.
  • Custom Actions:
  • version_calculation.py for semantic versioning.
  • update_changelog.py for changelog management.

Known Issues

  • Inconsistent changelog updates during pre-release workflows.
  • Potential gaps in tagging validation.

Gaps and Recommendations

  • Align release draft workflow with GitHub’s generation process.
  • Automate validation of tags and ensure consistency with semantic versioning.

3. Deployment Workflow

Purpose

  • Builds and deploys the documentation site via GitHub Pages.

Key Components

  • Pages Workflow: Automatically deploys changes from main to the GitHub Pages site.
  • MkDocs: Static site generator for documentation.

Tools and Actions

  • GitHub Actions:
  • mkdocs-gh-pages.yml for deployment.
  • Dependencies:
  • Listed in requirements.txt.

Known Issues

  • Occasional version mismatches between deployed site and repository source.
  • Lack of validation for MkDocs version consistency.

Gaps and Recommendations

  • Create a GitHub Action to validate MkDocs version consistency (back burner).
  • Add deployment logs for improved troubleshooting.

Testing Strategy

To ensure the reliability of these workflows:

  1. Unit Tests for Custom Actions:
    • Validate scripts like version_calculation.py and update_changelog.py.
  2. Integration Tests:
    • Simulate end-to-end workflows to confirm alignment.
  3. Manual QA:
    • Periodically review Pages deployments for accuracy.

Documentation Goals

  • Create detailed guides for each workflow in the docs/ directory.
  • Ensure README and MkDocs documentation align with actual practices.
  • Maintain an up-to-date changelog that reflects all workflow updates.

Next Steps

  1. Audit Existing Workflows: Review YAML files and custom scripts for inconsistencies.
  2. Refine Documentation: Ensure all workflows are documented clearly and concisely.
  3. Test and Validate: Execute workflows to identify and fix gaps.
  4. Abstract and Generalize: Simplify changelog and versioning processes for flexibility.

Conclusion

By documenting, testing, and refining these workflows, the repository can achieve consistency, clarity, and alignment across development and deployment processes. These steps will help stabilize the repository and move toward the 0.1 milestone.