Skip to content

Commit d3a8958

Browse files
author
CalorieApp Maintainer
committed
automation: add branch protection guide, roadmap, tagging helper, release workflow
1 parent dd15037 commit d3a8958

3 files changed

Lines changed: 187 additions & 0 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Release (Tagged)
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
workflow_dispatch:
8+
inputs:
9+
tag:
10+
description: "Tag to release (e.g. v0.1.1-testnet)"
11+
required: false
12+
13+
permissions:
14+
contents: write
15+
16+
jobs:
17+
create-release:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: Checkout
21+
uses: actions/checkout@v4
22+
23+
- name: Derive tag
24+
id: vars
25+
run: |
26+
if [ -n "${{ github.event.inputs.tag }}" ]; then
27+
echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT
28+
else
29+
echo "tag=${GITHUB_REF##*/}" >> $GITHUB_OUTPUT
30+
fi
31+
echo "version=${GITHUB_REF##*/}" >> $GITHUB_OUTPUT
32+
33+
- name: Find release note
34+
id: note
35+
run: |
36+
TAG="${{ steps.vars.outputs.tag }}"
37+
BASE=${TAG#v}
38+
FILE="docs/RELEASE_NOTE_${BASE//./_^^}.md"
39+
# Fallback to testnet uppercase transform
40+
if [ ! -f "$FILE" ]; then
41+
ALT="docs/RELEASE_NOTE_${BASE//./_ | tr '[:lower:]' '[:upper:]' }.md"
42+
fi
43+
if [ -f "$FILE" ]; then
44+
echo "path=$FILE" >> $GITHUB_OUTPUT
45+
else
46+
echo "path=CHANGELOG.md" >> $GITHUB_OUTPUT
47+
fi
48+
49+
- name: Read body
50+
id: body
51+
run: |
52+
BODY_PATH="${{ steps.note.outputs.path }}"
53+
echo "Using body file: $BODY_PATH"
54+
echo 'BODY<<EOF' >> $GITHUB_OUTPUT
55+
sed 's/\r$//' "$BODY_PATH" >> $GITHUB_OUTPUT
56+
echo 'EOF' >> $GITHUB_OUTPUT
57+
58+
- name: Create Release
59+
uses: softprops/action-gh-release@v1
60+
with:
61+
tag_name: ${{ steps.vars.outputs.tag }}
62+
name: ${{ steps.vars.outputs.tag }}
63+
draft: false
64+
prerelease: true
65+
body: ${{ steps.body.outputs.BODY }}
66+
env:
67+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
68+
69+
- name: Summary
70+
run: echo "Release published for ${{ steps.vars.outputs.tag }}" >> $GITHUB_STEP_SUMMARY

‎docs/BRANCH_PROTECTION_GUIDE.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Branch Protection & PR Workflow Guide
2+
3+
## Purpose
4+
Establish a minimal, testnet-appropriate workflow that prevents direct pushes to `main`, enforces review, and preserves repository integrity while in beta.
5+
6+
## Recommended Settings (GitHub > Settings > Branches > Branch protection rules)
7+
1. Protected Branch: `main`
8+
2. Require a pull request before merging: ENABLE
9+
- Require approvals: 1 (increase to 2 post-team expansion)
10+
- Dismiss stale approvals on new commits: ENABLE
11+
- Require review from Code Owners (optional if CODEOWNERS added)
12+
3. Require status checks to pass before merging: ENABLE
13+
- Required checks: `CI (ubuntu-latest / Python 3.12)`, `CI (windows-latest / Python 3.12)`, `lint`, `codeql`
14+
- Optionally add coverage threshold checks later.
15+
4. Require branches to be up to date before merging: ENABLE (prevents merging outdated PR base)
16+
5. Require signed commits: OPTIONAL (enable if enforcing signature policy)
17+
6. Require linear history: ENABLE (no merge commits; squash or rebase only)
18+
7. Include administrators: ENABLE (ensures consistency)
19+
8. Restrict who can push to matching branches: ENABLE (limit to release automation if needed)
20+
9. Lock branch: DISABLED (still in active development)
21+
22+
## Pull Request Workflow
23+
1. Create feature or fix branch: `feature/<short-topic>` or `chore/<task>`.
24+
2. Implement changes with small logical commits.
25+
3. Run local tests: `pytest -q` and lint: `flake8 src tests`.
26+
4. Open PR targeting `main`; include concise summary, risk section, and test evidence.
27+
5. Ensure required checks pass (CI matrix & lint). Fix issues before requesting review.
28+
6. Reviewer validates:
29+
- No accidental inclusion of deferred modules from `src/_deferred/`.
30+
- No secrets or wallet data artifacts.
31+
- Feature flags respected for experimental code.
32+
7. Merge strategy: **Squash** (recommended for beta) for clean history.
33+
34+
## Emergency Fix Protocol
35+
For critical testnet breakages:
36+
1. Branch `hotfix/<issue>` from `main`.
37+
2. Minimal patch only; no feature additions.
38+
3. PR with clear justification; expedite single approval.
39+
4. Post-merge, create follow-up issue for root cause analysis.
40+
41+
## Release Tagging
42+
1. Prepare release branch `release/v0.1.1-testnet`.
43+
2. Update `src/VERSION.py`, `CHANGELOG.md`, create `docs/RELEASE_NOTE_<VERSION>.md`.
44+
3. PR merge.
45+
4. Tag: `git tag -a v0.1.1-testnet -m "0.1.1-testnet <focus>"; git push origin v0.1.1-testnet`.
46+
5. GitHub Release auto-generated by workflow (see `.github/workflows/release.yml`).
47+
48+
## Deferred Feature Safeguards
49+
Before enabling `ENABLE_WEB3_BROWSER` or `ENABLE_CALORIE_DB`:
50+
1. Security review of dependencies & data flow.
51+
2. Add tests ensuring no sensitive leakage.
52+
3. Document activation rationale and rollback plan.
53+
4. Enable flag ONLY via PR with explicit reviewer sign-off.
54+
55+
## Prohibited in PRs
56+
| Action | Reason |
57+
|--------|--------|
58+
| Committing wallet seed/mnemonic | Security risk |
59+
| Reintroducing removed backup files | Privacy breach |
60+
| Activating deferred features silently | Undocumented surface expansion |
61+
| Bypassing tests/lint with forced merges | Stability regression |
62+
63+
## Future Enhancements
64+
- CODEOWNERS for security-sensitive paths.
65+
- Coverage threshold enforcement (>70% for core modules).
66+
- Secret scanning action on PR (GitHub Advanced Security or third-party).
67+
68+
## Testnet Disclaimer
69+
All merges assume testnet-only operation; production deployment requires separate audit phase and explicit version bump out of `-testnet` suffix.

‎docs/ROADMAP_NEXT_MILESTONE.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Roadmap: Next Milestone (Target: v0.1.1-testnet)
2+
3+
## Objective
4+
Incremental quality improvements: visual polish, accessibility, performance profiling, preparatory groundwork for optional CalorieDB activation.
5+
6+
## Pillars
7+
1. Visual Consistency & Spacing
8+
2. Accessibility & Contrast
9+
3. XRPL Performance Profiling
10+
4. Deferred Feature Security Modeling
11+
5. Release Automation Maturity
12+
13+
## Detailed Items
14+
| Category | Task | Notes |
15+
|----------|------|-------|
16+
| Visual | Normalize padding across form screens | Use consistent dp scale helpers |
17+
| Visual | Introduce design tokens (colors, spacing) | Centralize in `src/core/design_tokens.py` |
18+
| Accessibility | Contrast audit (AA baseline) | Add script to scan KV color usage |
19+
| Accessibility | Keyboard focus ring improvements | Extend `AccessibleButton` styling |
20+
| Performance | Profile XRPL failover latency | Add timed metrics & histogram logging |
21+
| Performance | Cache trustline queries | Reduce repeated `AccountLines` calls |
22+
| CalorieDB | Threat model draft | Document data surfaces & encryption boundaries |
23+
| CalorieDB | Anonymization verification tests | Ensure removal of PII before public sync |
24+
| Release Automation | Enforce PR-only tag creation | Guard via branch protection + workflow checks |
25+
| Tooling | Add secret scanning workflow | GitHub action or trufflehog integration |
26+
| Testing | Expand unit tests for feature flags | Ensure disabled state blocks imports |
27+
28+
## Stretch Goals
29+
- WalletConnect Phase 1 session handshake sandbox.
30+
- Dynamic theme accessibility auto-adjust (contrast-aware palette fallback).
31+
- Basic metric export endpoint (local debug only).
32+
33+
## Risks & Mitigations
34+
| Risk | Mitigation |
35+
|------|------------|
36+
| Premature CalorieDB exposure | Keep flags false; add activation checklist |
37+
| UI regression from spacing refactor | Snapshot KV layout diff; gradual module approach |
38+
| Performance tuning introduces race conditions | Add deterministic test harness wrappers |
39+
40+
## Exit Criteria (v0.1.1-testnet)
41+
- All visual spacing tasks merged.
42+
- Contrast audit summary committed.
43+
- XRPL latency metrics recorded & baseline documented.
44+
- CalorieDB threat model doc approved.
45+
- Release automation workflow validated via dry-run.
46+
47+
## Audit Reminder
48+
No production token/value features until post-threat model & second security audit.

0 commit comments

Comments
 (0)