gitea-mirror/Pulse
1
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-02-18 00:17:39 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
5a2d808aa16e01de3e1b163f1df3c711005891ce
Pulse/docs/CONTRIBUTING-SCRIPTS.md
rcourtman 0fcfad3dc5 feat: add shared script library system and refactor docker-agent installer 
Implements a comprehensive script improvement infrastructure to reduce code
duplication, improve maintainability, and enable easier testing of installer
scripts.

## New Infrastructure

### Shared Library System (scripts/lib/)
- common.sh: Core utilities (logging, sudo, dry-run, cleanup management)
- systemd.sh: Service management helpers with container-safe systemctl
- http.sh: HTTP/download helpers with curl/wget fallback and retry logic
- README.md: Complete API documentation for all library functions

### Bundler System
- scripts/bundle.sh: Concatenates library modules into single-file installers
- scripts/bundle.manifest: Defines bundling configuration for distributables
- Enables both modular development and curl|bash distribution

### Test Infrastructure
- scripts/tests/run.sh: Test harness for running all smoke tests
- scripts/tests/test-common-lib.sh: Common library validation (5 tests)
- scripts/tests/test-docker-agent-v2.sh: Installer smoke tests (4 tests)
- scripts/tests/integration/: Container-based integration tests (5 scenarios)
- All tests passing ✓

## Refactored Installer

### install-docker-agent-v2.sh
- Reduced from 1098 to 563 lines (48% code reduction)
- Uses shared libraries for all common operations
- NEW: --dry-run flag support
- Maintains 100% backward compatibility with original
- Fully tested with smoke and integration tests

### Key Improvements
- Sudo escalation: 100+ lines → 1 function call
- Download logic: 51 lines → 1 function call
- Service creation: 33 lines → 2 function calls
- Logging: Standardized across all operations
- Error handling: Improved with common library

## Documentation

### Rollout Strategy (docs/installer-v2-rollout.md)
- 3-phase rollout plan (Alpha → Beta → GA)
- Feature flag mechanism for gradual deployment
- Testing checklist and success metrics
- Rollback procedures and communication plan

### Developer Guides
- docs/script-library-guide.md: Complete library usage guide
- docs/CONTRIBUTING-SCRIPTS.md: Contribution workflow
- docs/installer-v2-quickref.md: Quick reference for operators

## Metrics

- Code reduction: 48% (1098 → 563 lines)
- Reusable functions: 0 → 30+
- Test coverage: 0 → 8 test scenarios
- Documentation: 0 → 5 comprehensive guides

## Testing

All tests passing:
- Smoke tests: 2/2 passed (8 test cases)
- Integration tests: 5/5 scenarios passed
- Bundled output: Syntax validated, dry-run tested

## Next Steps

This lays the foundation for migrating other installers (install.sh,
install-sensor-proxy.sh) to use the same pattern, reducing overall
maintenance burden and improving code quality across the project.
2025-10-20 15:13:38 +00:00

1.7 KiB
Raw Blame History

Contributing to Pulse Installer Scripts

Workflow Overview

  1. Plan the change (refactor, new feature, bugfix) and confirm whether the shared libraries already support your needs.
  2. Implement in the modular source file (e.g., scripts/install-foo-v2.sh).
  3. Add/Update tests (smoke + integration where applicable).
  4. Bundle (make bundle-scripts) and verify outputs.
  5. Document any behavioural changes.
  6. Submit PR with summary, testing results, and rollout considerations.

Expectations

  • Use shared libraries (scripts/lib/*.sh) instead of duplicating helpers.
  • Maintain backward compatibility; introduce feature flags when needed.
  • Keep legacy script versions until rollout completes.
  • Ensure scripts/tests/run.sh (smoke) and relevant integration tests pass.
  • Run make lint-scripts (shellcheck) before submitting.
  • Update scripts/bundle.manifest and regenerate bundles.
  • Provide before/after metrics when refactoring (size reduction, test coverage).

Testing Checklist

  • scripts/tests/run.sh
  • Relevant scripts/tests/integration/* scripts (add new ones if needed)
  • Manual --dry-run invocation of the script when feasible
  • Bundle validation: bash -n dist/<script>.sh and dist/<script>.sh --dry-run

Useful Commands

# Lint & format
make lint-scripts

# Run smoke tests
scripts/tests/run.sh

# Run integration tests
scripts/tests/integration/test-<name>.sh

# Rebuild bundles
make bundle-scripts

Resources

  • docs/script-library-guide.md — detailed patterns and examples
  • scripts/lib/README.md — library function reference
  • docs/installer-v2-rollout.md — rollout process for installers
  • GitHub Discussions / internal Slack for questions