Skip to content

Commit 6b7fd88

Browse files
JamesPHoughtonJamesPHoughton
committed
ai housekeeping
1 parent 5d8a735 commit 6b7fd88

8 files changed

Lines changed: 708 additions & 0 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Pull Request
2+
3+
## Description
4+
<!-- Brief summary of changes -->
5+
6+
## Related Issue
7+
Closes #
8+
9+
## Type of Change
10+
- [ ] Bug fix (non-breaking change which fixes an issue)
11+
- [ ] New feature (non-breaking change which adds functionality)
12+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
13+
- [ ] Documentation update
14+
- [ ] Refactoring (no functional changes)
15+
- [ ] Testing improvements
16+
17+
## Testing
18+
- [ ] Unit tests pass (`npm run test` in client/server)
19+
- [ ] E2E tests pass (Cypress)
20+
- [ ] Linting passes (`npm run lint`)
21+
- [ ] Manual testing completed
22+
- [ ] New tests added for new functionality
23+
24+
## Design Decisions
25+
<!-- Link to devLog entry if applicable (e.g., devLog/decisions/001-feature-name.md) -->
26+
<!-- For significant architectural changes, create a devLog entry before submitting PR -->
27+
28+
## Checklist
29+
- [ ] Code follows the project's style guidelines
30+
- [ ] Self-review of code completed
31+
- [ ] Comments added for complex logic
32+
- [ ] Documentation updated (if applicable)
33+
- [ ] No new warnings introduced
34+
- [ ] Empirica versions match across client/server/Dockerfile (if dependencies changed)
35+
36+
---
37+
38+
**Note for Agents**: When creating a PR programmatically, ensure:
39+
1. All checkboxes are accurately marked based on actual testing performed
40+
2. Related issue number is correctly linked
41+
3. If the change involves significant architectural decisions, create a devLog entry in `devLog/decisions/` and link it above
42+
4. Summary is clear and describes both *what* changed and *why*
43+
5. Use conventional commit format in the PR title (e.g., `feat(call): add feature`, `fix(server): resolve bug`)

‎.github/scripts/README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Workflow Scripts
2+
3+
This directory contains scripts to streamline the GitHub workflow for this repository.
4+
5+
## Available Scripts
6+
7+
### `start-issue.sh`
8+
9+
Starts work on a GitHub issue by creating a feature branch and displaying issue details.
10+
11+
**Usage:**
12+
```bash
13+
./.github/scripts/start-issue.sh ISSUE_NUMBER
14+
```
15+
16+
**What it does:**
17+
1. Fetches issue details from GitHub
18+
2. Ensures main branch is up to date (`git pull --ff-only`)
19+
3. Creates a new branch named `issue-{number}-{slugified-title}`
20+
4. Displays the full issue description for context
21+
5. Provides next steps for creating a PR
22+
23+
**Requirements:**
24+
- GitHub CLI (`gh`) installed and authenticated
25+
- Must be run from repository root
26+
27+
**Example:**
28+
```bash
29+
./.github/scripts/start-issue.sh 42
30+
# Creates branch: issue-42-add-dark-mode-toggle
31+
# Shows issue details
32+
# Ready to start coding
33+
```
34+
35+
### `post-merge.sh`
36+
37+
Cleans up local and remote branches after a PR has been merged.
38+
39+
**Usage:**
40+
```bash
41+
# From the feature branch:
42+
./.github/scripts/post-merge.sh
43+
44+
# Or specify a branch explicitly:
45+
./.github/scripts/post-merge.sh issue-42-add-dark-mode
46+
```
47+
48+
**What it does:**
49+
1. Switches to main branch (if on feature branch)
50+
2. Updates main from origin (`git pull --ff-only`)
51+
3. Deletes the local feature branch
52+
4. Optionally deletes the remote branch (prompts user)
53+
54+
**Requirements:**
55+
- Must be run from repository root
56+
- Branch to delete must exist locally
57+
58+
**Example:**
59+
```bash
60+
# After PR is merged on GitHub:
61+
./.github/scripts/post-merge.sh
62+
# Switches to main
63+
# Updates from origin
64+
# Deletes feature branch
65+
```
66+
67+
## Typical Workflow
68+
69+
1. **Start work on an issue:**
70+
```bash
71+
./.github/scripts/start-issue.sh 123
72+
```
73+
74+
2. **Make changes, commit, push:**
75+
```bash
76+
git add .
77+
git commit -m "feat: implement feature"
78+
git push -u origin issue-123-feature-name
79+
```
80+
81+
3. **Create PR:**
82+
```bash
83+
gh pr create --fill
84+
# Or use: gh pr create --web
85+
```
86+
87+
4. **After PR is merged:**
88+
```bash
89+
./.github/scripts/post-merge.sh
90+
```
91+
92+
## For AI Agents
93+
94+
When automating workflows:
95+
96+
1. **Starting work:** Always use `start-issue.sh` to ensure consistent branch naming and up-to-date main branch
97+
2. **Creating PRs:** Follow the [PR template](../.github/pull_request_template.md) and link to any relevant devLog entries
98+
3. **Post-merge:** Run `post-merge.sh` automatically (with `-y` flag if added) to keep the repository clean
99+
100+
## Future Enhancements
101+
102+
Potential additions:
103+
- `create-pr.sh` - Automate PR creation with filled template
104+
- `update-branch.sh` - Rebase feature branch on latest main
105+
- `run-checks.sh` - Run all CI checks locally before pushing

‎.github/scripts/post-merge.sh‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
#!/bin/bash
2+
# Usage: ./.github/scripts/post-merge.sh [BRANCH_NAME]
3+
#
4+
# This script cleans up after a PR has been merged:
5+
# 1. Switches to main branch
6+
# 2. Updates main from origin (fast-forward only)
7+
# 3. Deletes the local feature branch
8+
# 4. Optionally deletes the remote branch (if not auto-deleted)
9+
#
10+
# If BRANCH_NAME is not provided, uses the current branch
11+
12+
set -e
13+
14+
# Determine which branch to clean up
15+
if [ -z "$1" ]; then
16+
# No argument provided, use current branch
17+
BRANCH_NAME=$(git branch --show-current)
18+
19+
if [ "$BRANCH_NAME" = "main" ]; then
20+
echo "Error: Cannot run cleanup from main branch without specifying a branch name"
21+
echo "Usage: $0 [BRANCH_NAME]"
22+
exit 1
23+
fi
24+
25+
echo "Cleaning up current branch: ${BRANCH_NAME}"
26+
else
27+
BRANCH_NAME=$1
28+
echo "Cleaning up branch: ${BRANCH_NAME}"
29+
fi
30+
31+
# Safety check: don't delete main
32+
if [ "$BRANCH_NAME" = "main" ]; then
33+
echo "Error: Cannot delete main branch"
34+
exit 1
35+
fi
36+
37+
# Check if we're in a git repository
38+
if ! git rev-parse --git-dir > /dev/null 2>&1; then
39+
echo "Error: Not in a git repository"
40+
exit 1
41+
fi
42+
43+
# Check if branch exists locally
44+
if ! git show-ref --verify --quiet "refs/heads/${BRANCH_NAME}"; then
45+
echo "Error: Branch '${BRANCH_NAME}' does not exist locally"
46+
exit 1
47+
fi
48+
49+
echo ""
50+
echo "Post-merge cleanup for: ${BRANCH_NAME}"
51+
echo ""
52+
53+
# Switch to main if we're on the feature branch
54+
CURRENT_BRANCH=$(git branch --show-current)
55+
if [ "$CURRENT_BRANCH" = "$BRANCH_NAME" ]; then
56+
echo "Switching to main branch..."
57+
git checkout main
58+
fi
59+
60+
# Update main from origin
61+
echo "Updating main from origin..."
62+
git pull --ff-only
63+
64+
# Delete local branch
65+
echo "Deleting local branch: ${BRANCH_NAME}"
66+
git branch -d "${BRANCH_NAME}"
67+
68+
# Check if remote branch exists
69+
if git ls-remote --exit-code --heads origin "${BRANCH_NAME}" >/dev/null 2>&1; then
70+
echo ""
71+
echo "Remote branch 'origin/${BRANCH_NAME}' still exists."
72+
read -p "Do you want to delete it? (y/N) " -n 1 -r
73+
echo
74+
if [[ $REPLY =~ ^[Yy]$ ]]; then
75+
echo "Deleting remote branch..."
76+
git push origin --delete "${BRANCH_NAME}"
77+
echo "Remote branch deleted."
78+
else
79+
echo "Remote branch kept. You can delete it later with:"
80+
echo " git push origin --delete ${BRANCH_NAME}"
81+
fi
82+
else
83+
echo "Remote branch was already deleted (likely auto-deleted by GitHub)."
84+
fi
85+
86+
echo ""
87+
echo "========================================="
88+
echo "Cleanup complete!"
89+
echo "Current branch: main (up to date)"
90+
echo "Deleted local branch: ${BRANCH_NAME}"
91+
echo "========================================="

‎.github/scripts/start-issue.sh‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
#!/bin/bash
2+
# Usage: ./.github/scripts/start-issue.sh ISSUE_NUMBER
3+
#
4+
# This script helps start work on a GitHub issue by:
5+
# 1. Ensuring main branch is up to date
6+
# 2. Creating a new feature branch named after the issue
7+
# 3. Providing the issue details for context
8+
9+
set -e
10+
11+
# Check if issue number is provided
12+
if [ -z "$1" ]; then
13+
echo "Error: Issue number required"
14+
echo "Usage: $0 ISSUE_NUMBER"
15+
exit 1
16+
fi
17+
18+
ISSUE_NUM=$1
19+
20+
# Check if gh CLI is installed
21+
if ! command -v gh &> /dev/null; then
22+
echo "Error: GitHub CLI (gh) is not installed"
23+
echo "Install it from: https://cli.github.com/"
24+
exit 1
25+
fi
26+
27+
# Check if we're in a git repository
28+
if ! git rev-parse --git-dir > /dev/null 2>&1; then
29+
echo "Error: Not in a git repository"
30+
exit 1
31+
fi
32+
33+
# Fetch issue details
34+
echo "Fetching issue #${ISSUE_NUM}..."
35+
ISSUE_TITLE=$(gh issue view $ISSUE_NUM --json title -q .title 2>/dev/null)
36+
37+
if [ -z "$ISSUE_TITLE" ]; then
38+
echo "Error: Could not fetch issue #${ISSUE_NUM}"
39+
echo "Make sure the issue exists and you have access to it"
40+
exit 1
41+
fi
42+
43+
# Create branch name from issue title
44+
# Format: issue-{number}-{slugified-title}
45+
# Max 60 characters to keep branch names reasonable
46+
BRANCH_NAME="issue-${ISSUE_NUM}-$(echo "$ISSUE_TITLE" | \
47+
tr '[:upper:]' '[:lower:]' | \
48+
sed 's/[^a-z0-9]/-/g' | \
49+
sed 's/--*/-/g' | \
50+
sed 's/^-//' | \
51+
sed 's/-$//' | \
52+
cut -c1-50)"
53+
54+
echo ""
55+
echo "Issue: #${ISSUE_NUM} - ${ISSUE_TITLE}"
56+
echo "Branch: ${BRANCH_NAME}"
57+
echo ""
58+
59+
# Update main branch
60+
echo "Updating main branch..."
61+
git checkout main
62+
git pull --ff-only
63+
64+
# Check if branch already exists
65+
if git show-ref --verify --quiet "refs/heads/${BRANCH_NAME}"; then
66+
echo ""
67+
echo "Warning: Branch '${BRANCH_NAME}' already exists"
68+
read -p "Do you want to check it out anyway? (y/N) " -n 1 -r
69+
echo
70+
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
71+
echo "Aborted"
72+
exit 1
73+
fi
74+
git checkout "${BRANCH_NAME}"
75+
else
76+
# Create and checkout new branch
77+
echo "Creating branch: ${BRANCH_NAME}"
78+
git checkout -b "${BRANCH_NAME}"
79+
fi
80+
81+
# Display issue details
82+
echo ""
83+
echo "========================================="
84+
echo "Issue Details:"
85+
echo "========================================="
86+
gh issue view $ISSUE_NUM
87+
88+
echo ""
89+
echo "========================================="
90+
echo "Ready to work on issue #${ISSUE_NUM}!"
91+
echo "Branch: ${BRANCH_NAME}"
92+
echo ""
93+
echo "When done, create a PR with:"
94+
echo " gh pr create --fill"
95+
echo "========================================="

0 commit comments

Comments
 (0)