Skip to content

Latest commit

 

History

History
370 lines (257 loc) · 8.47 KB

contributing.md

File metadata and controls

370 lines (257 loc) · 8.47 KB

Contributing to Concourse

We welcome constructive contributions from everyone, regardless of skill level. This guide explains how to get involved in the Concourse community and contribute to the project.

Table of Contents

Getting Started

Sign the Contributor License Agreement

Before your contributions can be accepted, you must sign the Contributor License Agreement (CLA).

Join the Community

Understand the Codebase

Before contributing, familiarize yourself with:

  1. Architecture Overview - System design and components
  2. Developer Guide - Building and development workflow
  3. Testing Guide - Test frameworks and conventions

Development Setup

Prerequisites

  • Java 8 or higher
  • Git
  • Gradle (wrapper included)

Clone and Build

# Clone the repository
git clone https://github.com/cinchapi/concourse.git
cd concourse

# Install git hooks
./utils/install-git-hooks.sh

# Build the project
./gradlew build

IDE Setup

IntelliJ IDEA

  1. Open IntelliJ and select "Import Project"
  2. Choose the concourse directory
  3. Select "Import project from external model" → "Gradle"
  4. Use default Gradle wrapper

Eclipse

  1. Run ./gradlew eclipse to generate Eclipse project files
  2. In Eclipse, select "File" → "Import" → "Existing Projects into Workspace"
  3. Choose the concourse directory

Verify Setup

# Run tests to verify everything works
./gradlew test

# Build the installer
./gradlew installer

Issue Tracking

Finding Issues

  • Browse open issues on GitHub
  • Look for issues labeled good first issue for beginner-friendly tasks
  • Check the JIRA project for tracked work

Creating Issues

When creating a new issue:

  1. Search first: Check if a similar issue already exists
  2. Be specific: Provide clear steps to reproduce bugs
  3. Include context: Version, OS, Java version, relevant configuration

Bug Report Template

**Description**
A clear description of the bug.

**Steps to Reproduce**
1. Step one
2. Step two
3. ...

**Expected Behavior**
What should happen.

**Actual Behavior**
What actually happens.

**Environment**
- Concourse Version:
- Java Version:
- OS:

**Additional Context**
Any other relevant information.

Feature Request Template

**Description**
A clear description of the feature.

**Use Case**
Why this feature would be useful.

**Proposed Solution**
How you think it should work.

**Alternatives Considered**
Other approaches you've thought about.

Making Changes

Branch Naming

Use descriptive branch names:

feature/add-bulk-insert-api
bugfix/fix-transaction-timeout
docs/update-architecture-guide
refactor/simplify-lock-broker

Commit Messages

Write clear, descriptive commit messages:

Add bulk insert API for improved batch performance

- Implement bulkInsert() method in ConcourseServer
- Add corresponding driver method in Concourse.java
- Include unit and integration tests
- Update documentation

Fixes #123

Guidelines:

  • Use present tense ("Add feature" not "Added feature")
  • First line is a summary (50 chars or less)
  • Include details in the body if needed
  • Reference issues when applicable

Code Review Process

  1. Self-review: Review your own changes before submitting
  2. CI checks: Ensure all automated checks pass
  3. Reviewer feedback: Address all reviewer comments
  4. Approval: Wait for maintainer approval before merging

Testing Requirements

Required Tests

All changes should include appropriate tests:

Change Type Required Tests
New API method Unit test + Integration test
Bug fix Regression test in bugrepro/
Storage engine change Unit test + Integration test
Plugin framework change Unit test + Plugin test

Running Tests

# All tests
./gradlew test

# Specific module
./gradlew :concourse-server:test

# Specific test class
./gradlew :concourse-integration-tests:test --tests "*.AddTest"

# With detailed output
./gradlew test --info

Test Conventions

  • Test method names should be descriptive: testAddReturnsFalseWhenValueAlreadyExists
  • Use Variables.register() for debugging failed tests
  • Place bug reproductions in the bugrepro/ package

See Testing Guide for more details.

Submitting Pull Requests

Before Submitting

  1. Update your branch: Rebase on latest develop

    git fetch origin
git rebase origin/develop

  2. Run tests: Ensure all tests pass

    ./gradlew test

  3. Check formatting: Apply code style

    ./gradlew spotlessApply

  4. Build successfully: Verify full build works

    ./gradlew build

Pull Request Template

## Description
A clear description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Fixes #(issue number)

## Testing
Describe the tests you added or modified.

## Checklist
- [ ] My code follows the project's coding standards
- [ ] I have added tests for my changes
- [ ] All new and existing tests pass
- [ ] I have updated documentation as needed
- [ ] I have signed the CLA

After Submitting

  1. Monitor CI: Watch for build failures
  2. Respond to feedback: Address reviewer comments promptly
  3. Keep updated: Rebase if the target branch moves ahead

Code Style Enforcement

Spotless

Concourse uses Spotless for code formatting:

# Check formatting
./gradlew spotlessCheck

# Apply formatting
./gradlew spotlessApply

Pre-Push Hook

The git hooks installed by ./utils/install-git-hooks.sh automatically check formatting before push.

Style Configuration

Formatting rules are defined in:

  • spotless.java.license - License header
  • spotless.java.importerorder - Import ordering
  • spotless.java.eclipseformat.xml - Code formatting

Key Style Rules

  1. License Header: All Java files must have the Apache 2.0 license header
  2. Import Order: Organized by package (java, javax, third-party, project)
  3. Line Length: Reasonable line lengths (not strictly enforced)
  4. Braces: Opening brace on same line
  5. Indentation: 4 spaces (no tabs)

Getting Help

Questions

Stuck on an Issue?

  1. Check existing documentation and code comments
  2. Search closed issues and PRs for similar problems
  3. Ask on the mailing list with:
    • What you're trying to do
    • What you've tried
    • Any error messages

Want to Become a Regular Contributor?

Shoot us an email if you want to become a regular contributor and help with strategic planning!

Quick Reference

Useful Commands

# Build everything
./gradlew build

# Build without tests
./gradlew build -x test

# Run specific tests
./gradlew :module:test --tests "*.ClassName"

# Apply formatting
./gradlew spotlessApply

# Build installer
./gradlew installer

# Generate documentation
./gradlew javadoc

Key Files

File Purpose
build.gradle Root build configuration
settings.gradle Module definitions
CHANGELOG.md Release notes
interface/*.thrift API definitions

Related Documentation