Skip to content

Commit 1568061

Browse files
jonstjohnjonstjohn
committed
Export table/index identifiers, clean up documentation, add integration testing
1 parent 908bc03 commit 1568061

File tree

15 files changed

+1938
-175
lines changed

15 files changed

+1938
-175
lines changed

‎.github/DOCUMENTATION_STRUCTURE.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Documentation Structure
2+
3+
## Overview
4+
5+
The workload-exporter documentation has been organized to focus the main README on the primary audience (CockroachDB customers using pre-built releases) while providing comprehensive supporting documentation in the `docs/` directory.
6+
7+
## Main README (Customer-Focused)
8+
9+
**File:** `README.md`
10+
11+
**Target Audience:** CockroachDB customers who will download and use pre-built releases
12+
13+
**Focus Areas:**
14+
- ✅ What the tool does
15+
- ✅ Where to get pre-built binaries (releases page)
16+
- ✅ Quick start with minimal flags
17+
- ✅ Clear explanation of what data is collected
18+
- ✅ How to inspect exports before sharing
19+
- ✅ Privacy and security considerations
20+
- ✅ Common use cases
21+
- ✅ Links to detailed docs
22+
23+
**Key Sections:**
24+
1. What It Does - Clear value proposition
25+
2. Installation - Download links for macOS, Linux, Windows
26+
3. Quick Start - Simple examples
27+
4. Command Options - All available flags
28+
5. What Data is Collected - Complete transparency
29+
6. Inspecting the Export - How to review before sharing
30+
7. Privacy and Security - Builds trust
31+
8. Requirements - Prerequisites and permissions
32+
9. Common Use Cases - Real-world examples
33+
10. Getting Help - Troubleshooting and support links
34+
35+
## Supporting Documentation (`docs/`)
36+
37+
### For Users
38+
39+
#### `docs/TROUBLESHOOTING.md`
40+
Comprehensive troubleshooting guide covering:
41+
- Connection issues (SSL, authentication, network)
42+
- Permission problems
43+
- Time format errors
44+
- Empty exports
45+
- Debug logging
46+
- Common command patterns
47+
48+
#### `docs/COMPATIBILITY.md`
49+
Version compatibility information:
50+
- Supported CockroachDB versions (24.1+)
51+
- Version-specific behavior (26.1+ auto-enables allow_unsafe_internals)
52+
- Required permissions per version
53+
- Forward/backward compatibility
54+
- Upgrade considerations
55+
56+
### For Developers
57+
58+
#### `docs/DEVELOPMENT.md`
59+
Development and contribution guide:
60+
- Building from source
61+
- Development workflow
62+
- Make commands
63+
- Code structure
64+
- Contributing guidelines
65+
- Release process
66+
67+
#### `docs/TESTING.md`
68+
Testing documentation:
69+
- Unit tests
70+
- Integration tests (cross-version)
71+
- CI/CD integration
72+
- Performance expectations
73+
- Troubleshooting test issues
74+
75+
#### `docs/INTEGRATION_TEST_SUMMARY.md`
76+
Quick reference for the integration test implementation
77+
78+
#### `docs/LIBRARY.md`
79+
Go library usage:
80+
- Installation
81+
- API documentation
82+
- Example code
83+
- Advanced usage patterns
84+
- Error handling
85+
86+
#### `docs/README.md`
87+
Documentation index with links to all docs
88+
89+
## Documentation Principles
90+
91+
### 1. Customer-First README
92+
The main README assumes the user:
93+
- Wants to download a pre-built binary
94+
- Needs to understand what data will be collected
95+
- Wants to quickly get started
96+
- May need to share exports with Cockroach Labs support
97+
- Cares about privacy and security
98+
99+
### 2. Progressive Disclosure
100+
- Essential information in main README
101+
- Detailed information in topic-specific docs
102+
- Clear navigation between docs
103+
104+
### 3. Transparency
105+
- Explicit listing of all collected data
106+
- Instructions for inspecting exports
107+
- Privacy and security section
108+
- No hidden behavior
109+
110+
### 4. Separation of Concerns
111+
- **User docs** (troubleshooting, compatibility) separate from **developer docs** (development, testing, library)
112+
- Each doc has a single, clear purpose
113+
- Minimal duplication
114+
115+
## File Organization
116+
117+
```
118+
workload-exporter/
119+
├── README.md # Customer-focused main README
120+
├── LICENSE # MIT license
121+
├── Makefile # Build automation
122+
├── go.mod # Go dependencies
123+
├── cmd/ # CLI code
124+
├── pkg/ # Core library code
125+
├── docs/ # All supporting documentation
126+
│ ├── README.md # Documentation index
127+
│ ├── COMPATIBILITY.md # Version compatibility
128+
│ ├── TROUBLESHOOTING.md # Solutions to common issues
129+
│ ├── DEVELOPMENT.md # Building and contributing
130+
│ ├── TESTING.md # Testing guide
131+
│ ├── INTEGRATION_TEST_SUMMARY.md # Integration test reference
132+
│ └── LIBRARY.md # Go library usage
133+
└── .github/
134+
└── DOCUMENTATION_STRUCTURE.md # This file
135+
```
136+
137+
## Content Migration
138+
139+
### What Stayed in README
140+
- Installation (download links)
141+
- Basic usage examples
142+
- What data is collected
143+
- How to inspect exports
144+
- Privacy/security assurances
145+
- Common use cases
146+
147+
### What Moved to docs/
148+
- **TROUBLESHOOTING.md** - All troubleshooting content
149+
- **COMPATIBILITY.md** - Version compatibility details
150+
- **DEVELOPMENT.md** - Building from source, contributing
151+
- **LIBRARY.md** - Using as a Go library
152+
- **TESTING.md** - Testing guides (already existed)
153+
154+
## Benefits of This Structure
155+
156+
### For Customers
157+
✅ Quick path to download and use the tool
158+
✅ Clear understanding of what data is collected
159+
✅ Transparency builds trust
160+
✅ Easy to find troubleshooting help
161+
✅ Links to detailed docs when needed
162+
163+
### For Developers
164+
✅ Development docs separated from user docs
165+
✅ Clear contribution guidelines
166+
✅ Testing documentation preserved
167+
✅ Library usage well-documented
168+
169+
### For Maintainers
170+
✅ Easier to update specific topics
171+
✅ Less duplication
172+
✅ Clear organization
173+
✅ README stays focused and concise
174+
175+
## Navigation
176+
177+
All docs include:
178+
- Clear links to related documentation
179+
- Link back to main README
180+
- Link to GitHub issues for support
181+
- Link to releases page
182+
183+
The main README links to:
184+
- All topic-specific docs in "Additional Documentation" section
185+
- Troubleshooting guide in "Getting Help" section
186+
- Compatibility guide for version-specific behavior
187+
188+
## Keeping Documentation Current
189+
190+
When making changes:
191+
192+
1. **README updates** - Ensure main README stays customer-focused
193+
2. **Topic docs** - Update specific docs in `docs/` for detailed changes
194+
3. **Cross-references** - Update links when moving content
195+
4. **Index** - Update `docs/README.md` if adding new docs
196+
5. **Version info** - Update `COMPATIBILITY.md` for version-specific changes
197+
198+
## Review Checklist
199+
200+
When updating documentation:
201+
202+
- [ ] Is the main README still customer-focused?
203+
- [ ] Are download links prominent?
204+
- [ ] Is it clear what data is collected?
205+
- [ ] Are privacy/security concerns addressed?
206+
- [ ] Do links to docs/ work correctly?
207+
- [ ] Is technical/developer content in docs/?
208+
- [ ] Is the docs/README.md index up to date?
209+
- [ ] Are examples tested and working?

‎Makefile‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.PHONY: help build test test-integration lint clean
2+
3+
help: ## Show this help message
4+
@echo 'Usage: make [target]'
5+
@echo ''
6+
@echo 'Available targets:'
7+
@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf " %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
8+
9+
build: ## Build the workload-exporter binary
10+
go build -o workload-exporter
11+
12+
test: ## Run unit tests
13+
go test -v ./...
14+
15+
test-integration: ## Run integration tests against multiple CockroachDB versions
16+
@echo "Running integration tests..."
17+
@echo "Note: This will download CockroachDB binaries (cached after first run)"
18+
@echo "This may take several minutes..."
19+
go test -tags=integration -v -timeout=20m ./pkg/export/
20+
21+
lint: ## Run linter
22+
golangci-lint run --timeout=5m
23+
24+
clean: ## Clean build artifacts
25+
rm -f workload-exporter
26+
go clean -testcache

0 commit comments

Comments
 (0)