|
1 | | -# Project Management Scripts |
| 1 | +# Scripts Directory |
2 | 2 |
|
3 | | -This directory contains scripts for managing GitHub issues and project synchronization. |
| 3 | +This directory contains scripts essential for the development and maintenance of ag-grid-react-components. |
4 | 4 |
|
5 | | -## 🚀 Quick Start |
| 5 | +## Directory Structure |
6 | 6 |
|
7 | | -To bootstrap everything at once: |
| 7 | +``` |
| 8 | +scripts/ |
| 9 | +├── dev/ # Development utilities |
| 10 | +├── quality/ # Code quality tools |
| 11 | +├── build/ # Build and release utilities |
| 12 | +├── release/ # Release management |
| 13 | +└── utils/ # Shared utilities |
| 14 | +``` |
8 | 15 |
|
9 | | -```bash |
10 | | -npm run bootstrap:project |
11 | | -```text |
| 16 | +## Scripts by Category |
12 | 17 |
|
13 | | -Or run the shell script directly: |
| 18 | +### Development Scripts (`/dev`) |
14 | 19 |
|
15 | | -```bash |
16 | | -./scripts/bootstrap-all.sh |
17 | | -```text |
| 20 | +| Script | Purpose | Usage | |
| 21 | +|--------|---------|-------| |
| 22 | +| `pre-push.sh` | Comprehensive pre-push validation | Automatically run by git pre-push hook | |
| 23 | +| `pre-push-quick.sh` | Quick pre-push validation (skips tests) | `npm run pre-push:quick` | |
| 24 | +| `validate-demo.js` | Validates demo functionality | `npm run test:browser` | |
| 25 | +| `thorough-demo-check.js` | Comprehensive demo validation | `npm run test:thorough` | |
| 26 | +| `test-filter-click.js` | Tests filter click functionality | `npm run test:filter-click` | |
18 | 27 |
|
19 | | -## 📜 Available Scripts |
| 28 | +### Code Quality Scripts (`/quality`) |
20 | 29 |
|
21 | | -### bootstrap-all.sh |
22 | | -Complete bootstrap that runs all scripts in the correct order: |
23 | | -1. Adds missing required labels to issues |
24 | | -2. Syncs project fields to issue labels |
25 | | -3. Triggers GitHub Actions for final sync |
| 30 | +| Script | Purpose | Usage | |
| 31 | +|--------|---------|-------| |
| 32 | +| `check-whitespace.sh` | Checks for whitespace issues | `npm run check:whitespace` | |
| 33 | +| `fix-whitespace.sh` | Fixes whitespace issues | `npm run fix:whitespace` | |
| 34 | +| `check-codeql.js` | Validates CodeQL configuration | `npm run check:codeql` | |
| 35 | +| `check-fonts.js` | Checks font usage in code blocks | Direct execution | |
| 36 | +| `test-code-block-fonts.js` | Tests font rendering in code blocks | Direct execution | |
26 | 37 |
|
27 | | -### add-missing-labels.js |
28 | | -Ensures all issues have required labels: |
29 | | -- Adds default type label if missing (enhancement) |
30 | | -- Adds default priority label if missing (medium) |
31 | | -- Adds default area label if missing (components) |
32 | | -- Adds default status label if missing (needs-triage) |
| 38 | +### Build Scripts (`/build`) |
33 | 39 |
|
34 | | -```bash |
35 | | -node scripts/add-missing-labels.js |
36 | | -```text |
| 40 | +| Script | Purpose | Usage | |
| 41 | +|--------|---------|-------| |
| 42 | +| `generate-version-info.js` | Generates version info for demos | Automatically run during build | |
| 43 | +| `generate-og-image.js` | Generates Open Graph images | Direct execution | |
| 44 | +| `publish-local.sh` | Publishes package locally for testing | Direct execution | |
37 | 45 |
|
38 | | -### bootstrap-project-sync.js |
39 | | -Syncs all project field values to issue labels: |
40 | | -- Reads current project field values |
41 | | -- Updates issue labels to match |
42 | | -- Removes conflicting labels |
43 | | -- Handles all field types (Priority, Area, Type, Component, Status) |
| 46 | +### Release Scripts (`/release`) |
44 | 47 |
|
45 | | -```bash |
46 | | -node scripts/bootstrap-project-sync.js |
47 | | -```text |
| 48 | +| Script | Purpose | Usage | |
| 49 | +|--------|---------|-------| |
| 50 | +| `bump-version.js` | Bumps package version | Part of release workflow | |
| 51 | +| `generate-changelog.js` | Generates changelog entries | Part of release workflow | |
| 52 | +| `prepare-release.js` | Prepares release artifacts | Part of release workflow | |
48 | 53 |
|
49 | | -## 🔄 How Sync Works |
| 54 | +### Utility Scripts (`/utils`) |
50 | 55 |
|
51 | | -1. **Project → Labels**: When you change a field in the project, labels update automatically |
52 | | -2. **Labels → Project**: When you change labels on an issue, project fields update automatically |
53 | | -3. **Bidirectional**: Changes in either place stay synchronized |
| 56 | +| Script | Purpose | Usage | |
| 57 | +|--------|---------|-------| |
| 58 | +| `run-tsx.js` | Runs TypeScript files directly | `npm run run-tsx <file>` | |
| 59 | +| `loader.js` | TypeScript loader for Node.js | Used by run-tsx.js | |
| 60 | +| `ensure-project-root.mjs` | Ensures scripts run from project root | Imported by other scripts | |
54 | 61 |
|
55 | | -## 📋 Label Categories |
| 62 | +## Script Requirements |
56 | 63 |
|
57 | | -### Required Labels (one from each) |
58 | | -- **Type**: bug, enhancement, documentation, question |
59 | | -- **Priority**: priority: critical/high/medium/low |
60 | | -- **Area**: area: components/demo/build/ci-cd/testing/docs |
| 64 | +### Environment Variables |
61 | 65 |
|
62 | | -### Optional Labels |
63 | | -- **Status**: status: needs-triage/triaging/backlog/in-progress/in-review/done |
64 | | -- **Component**: component: date-filter/quick-filter-dropdown/active-filters/etc |
| 66 | +Most scripts don't require environment variables, but some GitHub-related scripts (now archived) required: |
| 67 | +- `GITHUB_TOKEN`: For GitHub API access |
| 68 | +- `NODE_ENV`: Development/production environment |
65 | 69 |
|
66 | | -## 🛠️ Troubleshooting |
| 70 | +### Dependencies |
67 | 71 |
|
68 | | -### "Command not found" error |
69 | | -Make sure you have Node.js installed and the GitHub CLI: |
70 | | -```bash |
71 | | -# Install GitHub CLI |
72 | | -brew install gh |
| 72 | +Scripts assume the following tools are installed: |
| 73 | +- Node.js (v18+) |
| 74 | +- npm (v10+) |
| 75 | +- Git |
| 76 | +- GitHub CLI (`gh`) for release scripts |
73 | 77 |
|
74 | | -# Authenticate |
75 | | -gh auth login |
76 | | -```text |
| 78 | +## Best Practices |
77 | 79 |
|
78 | | -### "GraphQL request failed" error |
79 | | -Your GitHub token might not have the right permissions: |
80 | | -```bash |
81 | | -# Check current auth status |
82 | | -gh auth status |
| 80 | +1. **Always run scripts from project root**: Most scripts use `ensure-project-root.mjs` to enforce this |
| 81 | +2. **Use npm scripts when available**: Prefer `npm run <script>` over direct execution |
| 82 | +3. **Check script headers**: Each script has a header comment explaining its purpose |
| 83 | +4. **Test locally first**: Especially for scripts that modify files or interact with GitHub |
83 | 84 |
|
84 | | -# Re-authenticate with proper scopes |
85 | | -gh auth login --scopes "repo,project" |
86 | | -``` |
| 85 | +## Archived Scripts |
| 86 | + |
| 87 | +Many scripts have been moved to `scripts-archive/` (git-ignored) for historical reference: |
87 | 88 |
|
88 | | -### Issues not updating |
89 | | -1. Check that the issue is in the project |
90 | | -2. Verify field values are set in the project |
91 | | -3. Run `gh issue view <number>` to see current labels |
| 89 | +- **Bot Automation** (`scripts-archive/bot-automation/`): GitHub project sync, bot workflows |
| 90 | +- **One-Time Scripts** (`scripts-archive/one-time/`): Setup scripts, migrations, fixes |
92 | 91 |
|
93 | | -## 🤖 Automation |
| 92 | +These scripts are preserved but not actively maintained. If you need functionality from an archived script, consider if it should be restored and updated. |
94 | 93 |
|
95 | | -After bootstrap, the system maintains itself: |
96 | | -- GitHub Actions run every 5 minutes |
97 | | -- Changes sync automatically |
98 | | -- Manual trigger available in Actions tab |
| 94 | +## Adding New Scripts |
99 | 95 |
|
100 | | -## 📊 Monitoring |
| 96 | +When adding new scripts: |
101 | 97 |
|
102 | | -View sync status: |
103 | | -- [GitHub Actions]([https://github.com/ryanrozich/ag-grid-react-components/action](https://github.com/ryanrozich/ag-grid-react-components/action)s) |
104 | | -- [Project Board]([https://github.com/users/ryanrozich/projects/](https://github.com/users/ryanrozich/projects/)1) |
105 | | -- [Issues List]([https://github.com/ryanrozich/ag-grid-react-components/issue](https://github.com/ryanrozich/ag-grid-react-components/issue)s) |
| 98 | +1. Place in the appropriate subdirectory |
| 99 | +2. Add a header comment with purpose and usage |
| 100 | +3. Update this README |
| 101 | +4. Consider if it needs to be added to package.json |
| 102 | +5. Use `ensure-project-root.mjs` for scripts that modify files |
| 103 | +6. Follow existing patterns for error handling and logging |
0 commit comments