Add comprehensive scripts documentation
- Create scripts/README.md with detailed documentation - Document all script categories and their usage - Add examples and best practices - Include CI integration information Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
288
scripts/README.md
Normal file
288
scripts/README.md
Normal file
@@ -0,0 +1,288 @@
|
||||
<!-- Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
|
||||
|
||||
This file is part of a Moko Consulting project.
|
||||
|
||||
SPDX-License-Identifier: GPL-3.0-or-later
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program. If not, see https://www.gnu.org/licenses/ .
|
||||
|
||||
FILE INFORMATION
|
||||
DEFGROUP: Moko-Cassiopeia.Documentation
|
||||
INGROUP: Scripts.Documentation
|
||||
REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
|
||||
FILE: ./scripts/README.md
|
||||
VERSION: 01.00.00
|
||||
BRIEF: Documentation for repository automation scripts
|
||||
-->
|
||||
|
||||
# Scripts Directory
|
||||
|
||||
This directory contains automation scripts for repository management, validation,
|
||||
and release processes for the Moko-Cassiopeia Joomla template.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── fix/ # Scripts that automatically fix common issues
|
||||
├── lib/ # Shared library functions
|
||||
├── release/ # Release automation scripts
|
||||
├── run/ # Execution and testing scripts
|
||||
└── validate/ # Validation and linting scripts
|
||||
```
|
||||
|
||||
## Library Files (`lib/`)
|
||||
|
||||
### `common.sh`
|
||||
Core utilities used by all scripts:
|
||||
- Environment normalization
|
||||
- Logging functions (`log_info`, `log_warn`, `log_error`, `die`)
|
||||
- Validation helpers (`assert_file_exists`, `assert_dir_exists`)
|
||||
- JSON utilities (`json_escape`, `json_output`)
|
||||
- Path helpers (`script_root`, `normalize_path`)
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
. "$(dirname "$0")/../lib/common.sh"
|
||||
log_info "Starting process..."
|
||||
```
|
||||
|
||||
### `joomla_manifest.sh`
|
||||
Joomla manifest parsing utilities:
|
||||
- `find_manifest <src_dir>` - Find primary Joomla manifest XML
|
||||
- `get_manifest_version <manifest>` - Extract version from manifest
|
||||
- `get_manifest_name <manifest>` - Extract extension name
|
||||
- `get_manifest_type <manifest>` - Extract extension type
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
. "${SCRIPT_DIR}/lib/joomla_manifest.sh"
|
||||
MANIFEST="$(find_manifest src)"
|
||||
VERSION="$(get_manifest_version "${MANIFEST}")"
|
||||
```
|
||||
|
||||
### `logging.sh`
|
||||
Enhanced logging with structured output:
|
||||
- Colored output support (when in terminal)
|
||||
- Log levels: `log_debug`, `log_success`, `log_step`
|
||||
- Structured logging: `log_kv`, `log_item`, `log_section`
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
. "${SCRIPT_DIR}/lib/logging.sh"
|
||||
log_section "Starting validation"
|
||||
log_kv "Version" "${VERSION}"
|
||||
log_success "All checks passed"
|
||||
```
|
||||
|
||||
## Validation Scripts (`validate/`)
|
||||
|
||||
These scripts validate repository structure, code quality, and compliance.
|
||||
They are typically run in CI pipelines.
|
||||
|
||||
### `manifest.sh`
|
||||
Validates Joomla manifest XML structure and required fields.
|
||||
|
||||
### `version_alignment.sh`
|
||||
Checks that manifest version is documented in CHANGELOG.md.
|
||||
|
||||
### `php_syntax.sh`
|
||||
Validates PHP syntax using `php -l` on all PHP files.
|
||||
|
||||
### `xml_wellformed.sh`
|
||||
Validates that all XML files are well-formed.
|
||||
|
||||
### `tabs.sh`
|
||||
Detects tab characters in source files (enforces spaces).
|
||||
|
||||
### `paths.sh`
|
||||
Detects Windows-style path separators (backslashes).
|
||||
|
||||
### `no_secrets.sh`
|
||||
Scans for accidentally committed secrets and credentials.
|
||||
|
||||
### `license_headers.sh`
|
||||
Checks that source files contain SPDX license identifiers.
|
||||
|
||||
### `language_structure.sh`
|
||||
Validates Joomla language directory structure and INI files.
|
||||
|
||||
### `changelog.sh`
|
||||
Validates CHANGELOG.md structure and version entries.
|
||||
|
||||
## Fix Scripts (`fix/`)
|
||||
|
||||
These scripts automatically fix common issues detected by validation scripts.
|
||||
|
||||
### `tabs.sh`
|
||||
Replaces tab characters with spaces in YAML files.
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
./scripts/fix/tabs.sh
|
||||
```
|
||||
|
||||
### `paths.sh`
|
||||
Normalizes Windows-style path separators to forward slashes.
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
./scripts/fix/paths.sh [directory]
|
||||
```
|
||||
|
||||
### `versions.sh`
|
||||
Updates version numbers across repository files.
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
./scripts/fix/versions.sh <VERSION>
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
./scripts/fix/versions.sh 3.5.0
|
||||
```
|
||||
|
||||
Updates:
|
||||
- Manifest XML `<version>` tag
|
||||
- `package.json` version field
|
||||
- Version references in README.md
|
||||
|
||||
## Release Scripts (`release/`)
|
||||
|
||||
Scripts for release automation and version management.
|
||||
|
||||
### `update_changelog.sh`
|
||||
Inserts a new version entry in CHANGELOG.md.
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
./scripts/release/update_changelog.sh <VERSION>
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
./scripts/release/update_changelog.sh 03.05.00
|
||||
```
|
||||
|
||||
### `update_dates.sh`
|
||||
Normalizes release dates across manifests and CHANGELOG.
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
./scripts/release/update_dates.sh <YYYY-MM-DD> <VERSION>
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
./scripts/release/update_dates.sh 2025-01-15 03.05.00
|
||||
```
|
||||
|
||||
## Run Scripts (`run/`)
|
||||
|
||||
Execution and testing scripts.
|
||||
|
||||
### `smoke_test.sh`
|
||||
Runs basic smoke tests to verify repository health:
|
||||
- Repository structure validation
|
||||
- Manifest validation
|
||||
- Version alignment checks
|
||||
- PHP syntax validation
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
./scripts/run/smoke_test.sh
|
||||
```
|
||||
|
||||
Example output:
|
||||
```
|
||||
INFO: Running smoke tests for Moko-Cassiopeia repository
|
||||
INFO: Checking repository structure...
|
||||
INFO: ✓ Repository structure valid
|
||||
INFO: Checking Joomla manifest...
|
||||
INFO: Found manifest: src/templates/templateDetails.xml
|
||||
INFO: Extension: moko-cassiopeia (template) v03.05.00
|
||||
INFO: ✓ Manifest validation passed
|
||||
INFO: =========================================
|
||||
INFO: Smoke tests completed successfully
|
||||
INFO: =========================================
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Writing New Scripts
|
||||
|
||||
1. **Use the library functions**:
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
. "${SCRIPT_DIR}/lib/common.sh"
|
||||
```
|
||||
|
||||
2. **Include proper headers**:
|
||||
- Copyright notice
|
||||
- SPDX license identifier
|
||||
- FILE INFORMATION section with DEFGROUP, INGROUP, PATH, VERSION, BRIEF
|
||||
|
||||
3. **Follow error handling conventions**:
|
||||
```bash
|
||||
[ -f "${FILE}" ] || die "File not found: ${FILE}"
|
||||
require_cmd python3
|
||||
```
|
||||
|
||||
4. **Use structured output**:
|
||||
```bash
|
||||
log_info "Starting process..."
|
||||
log_success "Process completed"
|
||||
```
|
||||
|
||||
5. **Make scripts executable**:
|
||||
```bash
|
||||
chmod +x scripts/new-script.sh
|
||||
```
|
||||
|
||||
### Testing Scripts Locally
|
||||
|
||||
Run validation scripts before committing:
|
||||
```bash
|
||||
./scripts/validate/manifest.sh
|
||||
./scripts/validate/php_syntax.sh
|
||||
./scripts/validate/tabs.sh
|
||||
```
|
||||
|
||||
Run smoke tests:
|
||||
```bash
|
||||
./scripts/run/smoke_test.sh
|
||||
```
|
||||
|
||||
### CI Integration
|
||||
|
||||
Scripts are automatically executed in GitHub Actions workflows:
|
||||
- `.github/workflows/ci.yml` - Continuous integration
|
||||
- `.github/workflows/repo_health.yml` - Repository health checks
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Description |
|
||||
| ------- | ---------- | ------------------------------------- |
|
||||
| 01.00.00 | 2025-01-03 | Initial scripts documentation created |
|
||||
|
||||
## Metadata
|
||||
|
||||
- **Document:** scripts/README.md
|
||||
- **Repository:** https://github.com/mokoconsulting-tech/moko-cassiopeia
|
||||
- **Version:** 01.00.00
|
||||
- **Status:** Active
|
||||
Reference in New Issue
Block a user