Skip to content

Commit 4f6b6b4

Browse files
tmaiarototmaiaroto
committed
update documentation, add contributing guide
1 parent e50cd3f commit 4f6b6b4

File tree

3 files changed

+403
-18
lines changed

3 files changed

+403
-18
lines changed

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@ cmd/server/bin/sg
22
cmd/server/bin/ast-grep
33
cmd/server/server
44
coverage.out
5-
./server
5+
server
6+
bin
7+
rules
8+
.roo
69

710
# Binaries for programs and plugins
811
*.exe

‎CONTRIBUTING.md‎

Lines changed: 318 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,318 @@
1+
# Contributing to Context Sherpa
2+
3+
Welcome! We're excited that you're interested in contributing to Context Sherpa. This document provides comprehensive guidelines for contributing to the project, whether through code changes, documentation improvements, or community rule contributions.
4+
5+
## Table of Contents
6+
7+
- [Project Overview](#project-overview)
8+
- [Development Environment Setup](#development-environment-setup)
9+
- [Building and Testing](#building-and-testing)
10+
- [Code Standards and Conventions](#code-standards-and-conventions)
11+
- [Contribution Workflow](#contribution-workflow)
12+
- [Contributing Community Rules](#contributing-community-rules)
13+
- [Reporting Issues](#reporting-issues)
14+
- [Submitting Pull Requests](#submitting-pull-requests)
15+
- [Communication](#communication)
16+
- [Acknowledgments](#acknowledgments)
17+
18+
## Project Overview
19+
20+
Context Sherpa is an AI-powered code analysis MCP server that enables AI coding agents to:
21+
- Lint and validate code using ast-grep rules
22+
- Dynamically create, update, and remove linting rules based on natural language feedback
23+
- Access a community repository of pre-built rules
24+
- Provide a self-contained, cross-platform binary with no external dependencies
25+
26+
The project consists of:
27+
- **MCP Server**: Go-based server providing tools for AI agents
28+
- **Build System**: GitHub Actions workflow for cross-platform binaries
29+
- **Community Rules**: Public repository of shareable ast-grep rules
30+
31+
## Development Environment Setup
32+
33+
### Prerequisites
34+
35+
- **Go 1.21+**: [Install Go](https://golang.org/doc/install)
36+
- **Git**: For version control
37+
- **ast-grep binary**: For local development and testing
38+
39+
### 1. Clone the Repository
40+
41+
```bash
42+
git clone https://github.com/hackafterdark/context-sherpa.git
43+
cd context-sherpa
44+
```
45+
46+
### 2. Set Up the ast-grep Binary
47+
48+
Download the appropriate ast-grep binary for your platform:
49+
50+
1. Visit [ast-grep releases](https://github.com/ast-grep/ast-grep/releases/latest)
51+
2. Download the binary for your OS/architecture
52+
3. Place it in `cmd/server/bin/` with the name `ast-grep`
53+
54+
**Platform-specific instructions:**
55+
- **Linux/macOS**: `ast-grep` (no extension)
56+
- **Windows**: Download `ast-grep.exe`, then rename to `ast-grep` (remove .exe)
57+
58+
### 3. Install Development Dependencies
59+
60+
```bash
61+
# Install Go dependencies
62+
go mod download
63+
64+
# Install development tools (optional but recommended)
65+
go install github.com/cosmtrek/air@latest # For hot reloading during development
66+
```
67+
68+
### 4. Verify Setup
69+
70+
```bash
71+
# Test that everything works
72+
go test ./...
73+
74+
# Build the project
75+
go build -o context-sherpa ./cmd/server
76+
77+
# Verify the binary
78+
./context-sherpa --help
79+
```
80+
81+
## Building and Testing
82+
83+
### Build Commands
84+
85+
```bash
86+
# Build for current platform
87+
go build -o context-sherpa ./cmd/server
88+
89+
# Build with specific flags
90+
go build -ldflags "-X main.version=$(git describe --tags)" -o context-sherpa ./cmd/server
91+
92+
# Build for multiple platforms (using the project's build system)
93+
go run ./scripts/build/build.go # If available
94+
```
95+
96+
### Testing
97+
98+
```bash
99+
# Run all tests
100+
go test ./...
101+
102+
# Run tests with coverage
103+
go test -cover ./...
104+
105+
# Run tests for specific package
106+
go test ./internal/mcp/...
107+
108+
# Run tests with verbose output
109+
go test -v ./...
110+
111+
# Run benchmarks
112+
go test -bench=. ./...
113+
```
114+
115+
### Development Workflow
116+
117+
For active development, we recommend using a hot-reload tool:
118+
119+
```bash
120+
# Using air (if installed)
121+
air
122+
123+
# Or manually rebuild on changes
124+
find . -name "*.go" | entr -r go build -o context-sherpa ./cmd/server
125+
```
126+
127+
## Code Standards and Conventions
128+
129+
This project follows the Go community's best practices and conventions.
130+
131+
### General Guidelines
132+
133+
- **Write idiomatic Go**: Follow standard conventions for naming, structure, and style
134+
- **Prefer copying over abstraction**: Small amounts of utility code are better copied than abstracted into shared packages
135+
- **Variable naming**: Use short names for limited scope, longer names for broader scope
136+
- **Code formatting**: All code must be formatted with `go fmt`
137+
- **Documentation**: All exported types, functions, and constants must have godoc-compliant comments
138+
139+
### Logging
140+
141+
- Use `github.com/charmbracelet/log` for all application logging
142+
- Avoid standard `log` or `fmt` packages for application logging
143+
- Log levels should be appropriate for the context
144+
145+
### Testing
146+
147+
- **Unit tests required**: All new functions must have corresponding unit tests
148+
- **Test file naming**: `*_test.go` files alongside the code they test
149+
- **Test function naming**: `Test<FunctionName>` for unit tests
150+
- **Table-driven tests**: Use descriptive names for sub-tests
151+
- **Assertions**: Use `stretchr/testify/assert` or `stretchr/testify/require`
152+
153+
### Comments and Documentation
154+
155+
```go
156+
// MyFunction performs an important operation on the provided data.
157+
// It returns an error if the operation fails due to invalid input.
158+
//
159+
// Parameters:
160+
// - ctx: The request context for cancellation and timeouts
161+
// - data: The input data to process
162+
//
163+
// Returns:
164+
// - result: The processed result
165+
// - err: Any error that occurred during processing
166+
func MyFunction(ctx context.Context, data InputData) (OutputData, error) {
167+
// Implementation
168+
}
169+
```
170+
171+
## Contribution Workflow
172+
173+
### 1. Fork and Clone
174+
175+
1. Fork the repository on GitHub
176+
2. Clone your fork locally
177+
3. Add the upstream remote:
178+
179+
```bash
180+
git remote add upstream https://github.com/hackafterdark/context-sherpa.git
181+
```
182+
183+
### 2. Create a Feature Branch
184+
185+
```bash
186+
git checkout -b feature/amazing-feature
187+
# or
188+
git checkout -b fix/bug-description
189+
```
190+
191+
### 3. Make Your Changes
192+
193+
- Follow the code standards outlined above
194+
- Add tests for new functionality
195+
- Update documentation as needed
196+
- Ensure all tests pass
197+
- **Plan your work** (especially when using AI): Use the context from the `AGENT_DOCS/` directory and this `CONTRIBUTING.md` file to create or update a plan markdown file documenting your thought process, goals, and implementation approach. This provides valuable historical context for future contributors and helps maintain consistency across the project.
198+
- **Update agent rules if needed**: Consider updating `AGENTS.md` if your changes affect how AI agents should interact with the codebase, such as new patterns to follow, updated conventions, or modified workflows that agents need to be aware of.
199+
200+
### 4. Test Your Changes
201+
202+
```bash
203+
# Run the full test suite
204+
go test ./...
205+
206+
# Check for any linting issues
207+
go vet ./...
208+
209+
# Format your code
210+
go fmt ./...
211+
```
212+
213+
### 5. Commit Your Changes
214+
215+
```bash
216+
git add .
217+
git commit -m "Add: comprehensive feature description
218+
219+
- What the change does
220+
- Why it's needed
221+
- Any breaking changes
222+
- Testing performed"
223+
```
224+
225+
### 6. Push and Create Pull Request
226+
227+
```bash
228+
git push origin feature/amazing-feature
229+
```
230+
231+
Then visit your fork on GitHub and create a pull request against the main branch.
232+
233+
## Contributing Community Rules
234+
235+
The [Context Sherpa Community Rules](https://github.com/hackafterdark/context-sherpa-community-rules) repository is where users can share ast-grep rules for common patterns and best practices.
236+
237+
### Rule Contribution Process
238+
239+
1. **Create Your Rule**: Write an ast-grep rule in YAML format
240+
2. **Add Tests**: Include valid and invalid test cases
241+
3. **Submit PR**: Follow the community repository's contribution guidelines
242+
4. **Automated Validation**: CI will validate your rule against test cases
243+
244+
### Rule Format
245+
246+
```yaml
247+
id: your-rule-id
248+
language: go
249+
author: YourGitHubUsername
250+
message: "Clear description of what this rule catches"
251+
severity: error
252+
metadata:
253+
tags: ["security", "performance", "style"]
254+
description: "Detailed explanation of the rule's purpose and examples"
255+
rule:
256+
pattern: # Your ast-grep pattern here
257+
```
258+
259+
## Reporting Issues
260+
261+
We use GitHub Issues for bug reports and feature requests.
262+
263+
### Bug Reports
264+
265+
When reporting a bug, please include:
266+
267+
- **Clear title**: Summarize the issue
268+
- **Description**: Detailed description of the problem
269+
- **Steps to reproduce**: Exact steps to reproduce the issue
270+
- **Expected behavior**: What you expected to happen
271+
- **Actual behavior**: What actually happened
272+
- **Environment**: OS, Go version, Context Sherpa version
273+
- **Logs**: Any relevant error messages or logs
274+
275+
### Feature Requests
276+
277+
For feature requests, please include:
278+
279+
- **Use case**: Why this feature would be useful
280+
- **Description**: Detailed description of the proposed feature
281+
- **Examples**: Code examples or mockups if applicable
282+
- **Alternatives**: Alternative solutions you've considered
283+
284+
## Submitting Pull Requests
285+
286+
### PR Requirements
287+
288+
- **Tests**: All new code must include appropriate tests
289+
- **Documentation**: Update documentation for new features
290+
- **Linting**: Code must pass `go vet` and be formatted with `go fmt`
291+
- **Single responsibility**: Each PR should address one issue or feature
292+
- **Descriptive title**: Clear, concise title describing the change
293+
294+
### PR Process
295+
296+
1. **Create PR**: Use GitHub's PR interface
297+
2. **Fill template**: Complete all sections of the PR template
298+
3. **CI checks**: Ensure all CI checks pass
299+
4. **Review**: Address any reviewer feedback
300+
5. **Merge**: Maintainers will merge approved PRs
301+
302+
## Communication
303+
304+
- **GitHub Issues**: For bug reports and feature requests
305+
- **GitHub Discussions**: For questions and community discussion
306+
- **Email**: For security issues or private matters
307+
308+
## Acknowledgments
309+
310+
We'd like to thank:
311+
312+
- **ast-grep team**: For creating an amazing tool that powers Context Sherpa's pattern matching capabilities
313+
- **MCP-go contributors**: For the excellent Go implementation of the Model Context Protocol
314+
- **Our community**: For contributing rules, reporting issues, and helping improve the project
315+
316+
---
317+
318+
Thank you for contributing to Context Sherpa! Your efforts help make AI-assisted development safer and more reliable for everyone.

0 commit comments

Comments
 (0)