Skip to content

Commit 96765db

Browse files
mistercrunchmistercrunch
committed
feat: add CLAUDE.md and improve README.md
1 parent 0fa911d commit 96765db

File tree

2 files changed

+259
-25
lines changed

2 files changed

+259
-25
lines changed

‎CLAUDE.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
supersetbot is a utility bot for Apache Superset that helps with GitHub, CI, and related tasks. It can be used as a local CLI or invoked directly from GitHub comments for specific use cases.
8+
9+
## Development Commands
10+
11+
### Install and Run
12+
```bash
13+
nvm use 20
14+
npm install
15+
./src/supersetbot # or: npm run supersetbot
16+
```
17+
18+
### Testing
19+
```bash
20+
npm test # Runs Jest tests with experimental VM modules
21+
```
22+
23+
### Linting
24+
```bash
25+
npm run lint # Runs ESLint on all files
26+
```
27+
28+
## Architecture
29+
30+
### Core Components
31+
32+
- **CLI Interface** (`src/cli.js`): Commander-based CLI that defines all available commands and options
33+
- **Context** (`src/context.js`): Manages execution context (CLI vs GitHub Actions) and handles logging/output
34+
- **GitHub Integration** (`src/github.js`): Octokit-based GitHub API interactions with throttling support
35+
- **Git Operations** (`src/git.js`): Release management and PR labeling logic using simple-git
36+
- **Docker** (`src/docker.js`): Docker build command generation for CI/CD pipelines
37+
38+
### Command Categories
39+
40+
1. **Labeling Commands**: Add/remove labels, org labels, release labels
41+
2. **Release Management**: Auto-label PRs with release versions
42+
3. **Dependency Management**: Bump Python dependencies via automated PRs
43+
4. **Docker Operations**: Generate Docker build commands for various presets
44+
45+
### Key Design Patterns
46+
47+
- Commands are conditionally available based on execution context (CLI vs GitHub Actions)
48+
- Dry-run mode is supported across all commands for safety
49+
- Verbose mode provides detailed debugging output
50+
- The bot can parse commands from GitHub comments starting with `@supersetbot`
51+
52+
## Testing Approach
53+
54+
- Jest is configured for ES modules with `--experimental-vm-modules`
55+
- Test files follow the `*.test.js` naming convention
56+
- Tests exist for core modules: cli, docker, utils, and index
57+
58+
## Important Notes
59+
60+
- The bot requires Node.js 20 or higher
61+
- Uses ES modules (`"type": "module"` in package.json)
62+
- GitHub authentication is handled via environment variables
63+
- Rate limiting is built into GitHub API calls via @octokit/plugin-throttling

‎README.md‎

Lines changed: 196 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,41 +3,212 @@
33
<img width="300" alt="Screenshot 2024-04-02 at 11 03 46 PM" src="https://github.com/apache-superset/supersetbot/assets/487433/c3eb1414-f760-48d3-8a69-c99788247966">
44

55

6-
supersetbot is a utility bot that can be used to help around GitHub, CI and beyond.
6+
supersetbot is a utility bot that streamlines GitHub operations, CI/CD workflows, and release management for Apache Superset.
77

8-
The bot can be used as a local CLI OR, for a subset of fitted use cases, can be invoked directly
9-
from GitHub comments.
8+
The bot can be used as a local CLI OR, for a subset of fitted use cases, can be invoked directly from GitHub comments using `@supersetbot` commands.
109

11-
Because it's its own npm app, it can be tested/deployed/used in isolation from the rest of
12-
Superset, and take on some of the complexity from GitHub actions and onto a nifty
13-
utility that can be used in different contexts.
10+
Because it's its own npm app, it can be tested/deployed/used in isolation from the rest of Superset, and take on some of the complexity from GitHub actions and onto a nifty utility that can be used in different contexts.
1411

15-
## Features
12+
## Prerequisites
13+
14+
- Node.js 20 or higher
15+
- npm or yarn
16+
- Git
17+
- GitHub personal access token (for GitHub operations)
18+
19+
## Installation
20+
21+
### Global Installation
22+
```bash
23+
nvm use 20
24+
npm install -g supersetbot
25+
```
1626

27+
### Local Development
28+
```bash
29+
git clone https://github.com/apache-superset/supersetbot.git
30+
cd supersetbot
31+
nvm use 20
32+
npm install
1733
```
18-
$ nvm use 20
19-
$ npm i -g supersetbot
20-
$ supersetbot
21-
$ ./src/supersetbot
22-
Usage: supersetbot [options] [command]
2334

24-
Options:
35+
## Features
36+
37+
### Available Commands
38+
39+
```bash
40+
supersetbot [options] [command]
41+
42+
Global Options:
2543
-v, --verbose Output extra debugging information
2644
-r, --repo <repo> The GitHub repo to use (ie:"apache/superset")
2745
-d, --dry-run Run the command in dry-run mode
2846
-a, --actor <actor> The actor
2947
-h, --help display help for command
48+
```
49+
50+
#### Label Management
51+
52+
**Add a label to an issue or PR**
53+
```bash
54+
supersetbot label "v3.0" -i 12345
55+
supersetbot label "enhancement" -i 12345 -r apache/superset
56+
```
57+
58+
**Remove a label from an issue or PR**
59+
```bash
60+
supersetbot unlabel "needs-review" -i 12345
61+
```
62+
63+
**Add organization label based on author**
64+
```bash
65+
supersetbot orglabel -i 12345
66+
```
67+
68+
#### Release Management
3069

31-
Commands:
32-
label [options] <label> Add a label to an issue or PR
33-
unlabel [options] <label> Remove a label from an issue or PR
34-
orglabel [options] Add an org label based on the author
35-
release-label-pr [options] <prId> Figure out first release for PR and label it
36-
version Prints supersetbot's version number
37-
release-label-prs [options] Given a set of PRs, auto-release label them
38-
release-label [options] <release> Figure out first release for PR and label it
39-
bump-python [options] Submit PR(s) to bump python dependencies
40-
docker [options] Generates/run docker build commands use in CI
41-
run <command> Run a command from Github Action
42-
help [command] display help for command
70+
**Auto-label a PR with its release version**
71+
```bash
72+
supersetbot release-label-pr 12345
73+
supersetbot release-label-pr 12345 --exclude-cherries # Exclude cherry-picked commits
4374
```
75+
76+
**Batch label PRs for a specific release**
77+
```bash
78+
supersetbot release-label v3.0.0
79+
```
80+
81+
**Auto-label multiple merged PRs**
82+
```bash
83+
supersetbot release-label-prs --search "merged:>2024-01-01" --pages 5
84+
```
85+
86+
#### Python Dependencies
87+
88+
**Bump Python dependencies**
89+
```bash
90+
# Update all dependencies
91+
supersetbot bump-python
92+
93+
# Update specific package
94+
supersetbot bump-python -p pandas
95+
96+
# Update a group of dependencies
97+
supersetbot bump-python -g dev
98+
99+
# Create PRs with limits
100+
supersetbot bump-python --limit 5 --only-base
101+
```
102+
103+
#### Docker Operations
104+
105+
**Generate Docker build commands**
106+
```bash
107+
# Build lean image
108+
supersetbot docker --preset lean --platform linux/amd64
109+
110+
# Build for multiple platforms
111+
supersetbot docker --preset dev --platform linux/amd64 linux/arm64
112+
113+
# Build and push
114+
supersetbot docker --preset lean --push --context release --context-ref v3.0.0
115+
```
116+
117+
#### Utility Commands
118+
119+
**Get version**
120+
```bash
121+
supersetbot version
122+
```
123+
124+
## GitHub Integration
125+
126+
supersetbot can be invoked directly from GitHub comments in issues and PRs:
127+
128+
```
129+
@supersetbot label v3.0
130+
@supersetbot orglabel
131+
@supersetbot release-label-pr 12345
132+
```
133+
134+
The bot will process the command and respond with a comment containing the results.
135+
136+
## Architecture
137+
138+
supersetbot follows a modular architecture designed for extensibility and maintainability:
139+
140+
### Core Components
141+
142+
- **CLI Interface** (`src/cli.js`): Commander.js-based CLI that defines all available commands
143+
- **Context Manager** (`src/context.js`): Handles execution context (CLI vs GitHub Actions) and manages logging
144+
- **GitHub Client** (`src/github.js`): Octokit-based GitHub API wrapper with rate limiting and throttling
145+
- **Git Operations** (`src/git.js`): Release management and PR analysis using simple-git
146+
- **Docker Builder** (`src/docker.js`): Docker command generation for various build presets
147+
- **Utilities** (`src/utils.js`): Shared helper functions and shell command execution
148+
149+
### Key Design Patterns
150+
151+
- **Context-Aware Execution**: Commands behave differently based on execution environment
152+
- **Dry-Run Support**: All destructive operations support `--dry-run` for safety
153+
- **Verbose Logging**: Detailed debug output available with `--verbose` flag
154+
- **Error Resilience**: Graceful error handling with informative messages
155+
156+
## Development
157+
158+
### Running Locally
159+
160+
```bash
161+
# Run from source
162+
./src/supersetbot [command]
163+
164+
# Run tests
165+
npm test
166+
167+
# Lint code
168+
npm run lint
169+
```
170+
171+
### Environment Variables
172+
173+
- `GITHUB_TOKEN`: Required for GitHub API operations
174+
- `GITHUB_REPOSITORY`: Default repository (e.g., "apache/superset")
175+
- `GITHUB_ACTOR`: The user performing the action
176+
- `GITHUB_ISSUE_NUMBER`: Default issue/PR number for commands
177+
178+
### Testing
179+
180+
supersetbot uses Jest with ES modules support:
181+
182+
```bash
183+
# Run all tests
184+
npm test
185+
186+
# Run specific test file
187+
npm test src/utils.test.js
188+
189+
# Run with coverage
190+
npm test -- --coverage
191+
```
192+
193+
Test files follow the `*.test.js` naming convention and are colocated with source files.
194+
195+
## Contributing
196+
197+
1. Fork the repository
198+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
199+
3. Make your changes
200+
4. Run tests and linting
201+
5. Commit your changes
202+
6. Push to your fork
203+
7. Open a Pull Request
204+
205+
### Code Style
206+
207+
- ES modules with `import`/`export` syntax
208+
- ESLint with Airbnb configuration
209+
- Async/await for asynchronous operations
210+
- Commander.js for CLI structure
211+
212+
## License
213+
214+
Licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)