Add pull request capability
Change-Id: Ib54054cc9b32930764cc2110203742c3948f9ea3
diff --git a/server/git/PULL_REQUEST_README.md b/server/git/PULL_REQUEST_README.md
new file mode 100644
index 0000000..b6664f2
--- /dev/null
+++ b/server/git/PULL_REQUEST_README.md
@@ -0,0 +1,323 @@
+# Pull Request Capabilities
+
+This package now includes comprehensive pull request (PR) capabilities that support both GitHub and Gerrit platforms. The implementation provides a unified interface for managing pull requests across different code hosting platforms.
+
+## Features
+
+- **Unified Interface**: Same API for both GitHub and Gerrit
+- **Full CRUD Operations**: Create, read, update, delete pull requests
+- **Advanced Filtering**: List pull requests with various filters
+- **Merge Operations**: Support for different merge strategies
+- **Error Handling**: Comprehensive error handling with detailed messages
+- **Authentication**: Support for token-based and basic authentication
+
+## Supported Platforms
+
+### GitHub
+- Uses GitHub REST API v3
+- Supports personal access tokens for authentication
+- Full support for all pull request operations
+- Handles GitHub-specific features like draft PRs, labels, assignees, and reviewers
+
+### Gerrit
+- Uses Gerrit REST API
+- Supports HTTP password or API token authentication
+- Maps Gerrit "changes" to pull requests
+- Handles Gerrit-specific features like topics and review workflows
+
+## Quick Start
+
+### GitHub Example
+
+```go
+package main
+
+import (
+ "context"
+ "github.com/iomodo/staff/git"
+ "net/http"
+ "time"
+)
+
+func main() {
+ ctx := context.Background()
+
+ // Create GitHub configuration
+ githubConfig := git.GitHubConfig{
+ Token: "your-github-token",
+ BaseURL: "https://api.github.com",
+ HTTPClient: &http.Client{Timeout: 30 * time.Second},
+ }
+
+ // Create GitHub provider
+ githubProvider := git.NewGitHubPullRequestProvider("owner", "repo", githubConfig)
+
+ // Create Git instance with pull request capabilities
+ git := git.NewGitWithPullRequests("/path/to/repo", git.GitConfig{}, githubProvider)
+
+ // Create a pull request
+ prOptions := git.PullRequestOptions{
+ Title: "Add new feature",
+ Description: "This PR adds a new feature to the application.",
+ BaseBranch: "main",
+ HeadBranch: "feature/new-feature",
+ Labels: []string{"enhancement", "feature"},
+ Assignees: []string{"username1", "username2"},
+ Reviewers: []string{"reviewer1", "reviewer2"},
+ Draft: false,
+ }
+
+ pr, err := git.CreatePullRequest(ctx, prOptions)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ fmt.Printf("Created pull request: %s (#%d)\n", pr.Title, pr.Number)
+}
+```
+
+### Gerrit Example
+
+```go
+package main
+
+import (
+ "context"
+ "github.com/iomodo/staff/git"
+ "net/http"
+ "time"
+)
+
+func main() {
+ ctx := context.Background()
+
+ // Create Gerrit configuration
+ gerritConfig := git.GerritConfig{
+ Username: "your-username",
+ Password: "your-http-password-or-api-token",
+ BaseURL: "https://gerrit.example.com",
+ HTTPClient: &http.Client{Timeout: 30 * time.Second},
+ }
+
+ // Create Gerrit provider
+ gerritProvider := git.NewGerritPullRequestProvider("project-name", gerritConfig)
+
+ // Create Git instance with pull request capabilities
+ git := git.NewGitWithPullRequests("/path/to/repo", git.GitConfig{}, gerritProvider)
+
+ // Create a change (pull request)
+ prOptions := git.PullRequestOptions{
+ Title: "Add new feature",
+ Description: "This change adds a new feature to the application.",
+ BaseBranch: "master",
+ HeadBranch: "feature/new-feature",
+ }
+
+ pr, err := git.CreatePullRequest(ctx, prOptions)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ fmt.Printf("Created change: %s (#%d)\n", pr.Title, pr.Number)
+}
+```
+
+## API Reference
+
+### Types
+
+#### PullRequest
+Represents a pull request or merge request across platforms.
+
+```go
+type PullRequest struct {
+ ID string
+ Number int
+ Title string
+ Description string
+ State string // "open", "closed", "merged"
+ Author Author
+ CreatedAt time.Time
+ UpdatedAt time.Time
+ BaseBranch string
+ HeadBranch string
+ BaseRepo string
+ HeadRepo string
+ Labels []string
+ Assignees []Author
+ Reviewers []Author
+ Commits []Commit
+ Comments []PullRequestComment
+}
+```
+
+#### PullRequestOptions
+Options for creating or updating pull requests.
+
+```go
+type PullRequestOptions struct {
+ Title string
+ Description string
+ BaseBranch string
+ HeadBranch string
+ BaseRepo string
+ HeadRepo string
+ Labels []string
+ Assignees []string
+ Reviewers []string
+ Draft bool
+}
+```
+
+#### ListPullRequestOptions
+Options for listing pull requests.
+
+```go
+type ListPullRequestOptions struct {
+ State string // "open", "closed", "all"
+ Author string
+ Assignee string
+ BaseBranch string
+ HeadBranch string
+ Labels []string
+ Limit int
+}
+```
+
+#### MergePullRequestOptions
+Options for merging pull requests.
+
+```go
+type MergePullRequestOptions struct {
+ MergeMethod string // "merge", "squash", "rebase"
+ CommitTitle string
+ CommitMsg string
+}
+```
+
+### Methods
+
+#### CreatePullRequest
+Creates a new pull request.
+
+```go
+func (g *Git) CreatePullRequest(ctx context.Context, options PullRequestOptions) (*PullRequest, error)
+```
+
+#### GetPullRequest
+Retrieves a pull request by ID.
+
+```go
+func (g *Git) GetPullRequest(ctx context.Context, id string) (*PullRequest, error)
+```
+
+#### ListPullRequests
+Lists pull requests with optional filtering.
+
+```go
+func (g *Git) ListPullRequests(ctx context.Context, options ListPullRequestOptions) ([]PullRequest, error)
+```
+
+#### UpdatePullRequest
+Updates an existing pull request.
+
+```go
+func (g *Git) UpdatePullRequest(ctx context.Context, id string, options PullRequestOptions) (*PullRequest, error)
+```
+
+#### ClosePullRequest
+Closes a pull request.
+
+```go
+func (g *Git) ClosePullRequest(ctx context.Context, id string) error
+```
+
+#### MergePullRequest
+Merges a pull request.
+
+```go
+func (g *Git) MergePullRequest(ctx context.Context, id string, options MergePullRequestOptions) error
+```
+
+## Configuration
+
+### GitHub Configuration
+
+```go
+type GitHubConfig struct {
+ Token string // GitHub personal access token
+ BaseURL string // GitHub API base URL (default: https://api.github.com)
+ HTTPClient *http.Client // Custom HTTP client (optional)
+}
+```
+
+### Gerrit Configuration
+
+```go
+type GerritConfig struct {
+ Username string // Gerrit username
+ Password string // HTTP password or API token
+ BaseURL string // Gerrit instance URL
+ HTTPClient *http.Client // Custom HTTP client (optional)
+}
+```
+
+## Error Handling
+
+All pull request operations return detailed error information through the `GitError` type:
+
+```go
+type GitError struct {
+ Command string
+ Output string
+ Err error
+}
+```
+
+Common error scenarios:
+- Authentication failures
+- Invalid repository or project names
+- Network connectivity issues
+- API rate limiting
+- Invalid pull request data
+
+## Platform-Specific Notes
+
+### GitHub
+- Requires a personal access token with appropriate permissions
+- Supports draft pull requests
+- Full support for labels, assignees, and reviewers
+- Uses GitHub's REST API v3
+
+### Gerrit
+- Requires HTTP password or API token
+- Uses "changes" instead of "pull requests"
+- Topics are used to group related changes
+- Review workflow is more structured
+- Uses Gerrit's REST API
+
+## Examples
+
+See `pull_request_example.go` for comprehensive examples of using both GitHub and Gerrit providers.
+
+## Testing
+
+Run the tests to ensure everything works correctly:
+
+```bash
+go test ./git/... -v
+```
+
+## Contributing
+
+When adding support for new platforms:
+
+1. Implement the `PullRequestProvider` interface
+2. Add platform-specific configuration types
+3. Create conversion functions to map platform-specific data to our unified types
+4. Add comprehensive tests
+5. Update this documentation
+
+## License
+
+This code is part of the staff project and follows the same licensing terms.
\ No newline at end of file