Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
267 lines (189 loc) · 5.54 KB

CONTRIBUTING.md

File metadata and controls

267 lines (189 loc) · 5.54 KB

Contributing to gitconfig

Thank you for your interest in contributing to gitconfig! This document provides guidelines and instructions for contributing.

Code of Conduct

Please be respectful and constructive in all interactions within this project.

Getting Started

Prerequisites

  • Go 1.24 or later
  • Git
  • Make

Development Setup

  1. Clone the repository:
git clone https://github.com/gopasspw/gitconfig.git
cd gitconfig
  1. Install dependencies:
go mod tidy
  1. Verify your setup:
make test
make codequality

All tests should pass and no linting errors should be reported.

Making Changes

Please see Development Workflow.

Testing

Running Tests

# Run all tests
make test

# Run specific test
go test -v -run TestName

# Run with race detection
go test -race ./...

Writing Tests

  1. Test location: Add tests to *_test.go files next to source code
  2. Test naming: Use TestFunctionName or TestFunctionName_Scenario
  3. Test structure: Use table-driven tests where practical
  4. Parallel tests: Add t.Parallel() to tests that don't rely on shared state
  5. Assertions: Use testify/assert and testify/require

Example test:

func TestMyFeature(t *testing.T) {
 t.Parallel()

 testCases := []struct {
  name    string
  input   string
  want    string
  wantErr bool
 }{
  {
   name:    "simple case",
   input:   "test",
   want:    "result",
   wantErr: false,
  },
 }

 for _, tc := range testCases {
  t.Run(tc.name, func(t *testing.T) {
   got, err := MyFunction(tc.input)
   if tc.wantErr {
    assert.Error(t, err)
   } else {
    assert.NoError(t, err)
    assert.Equal(t, tc.want, got)
   }
  })
 }
}

Test Coverage

When adding new functionality:

  • Aim for >80% code coverage
  • Test both the success path and error cases
  • Include edge case tests
  • Document why certain edge cases are important

Commit Messages

Use conventional commit format:

type(scope): short description

Longer explanation if needed. Wrap at 72 characters.

Additional context and motivation.

Fixes #123

Common types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation change
  • test: Test addition or modification
  • refactor: Code refactoring
  • perf: Performance improvement
  • chore: Build, dependencies, or tooling

Example:

feat(parser): add support for bare boolean values

Add parsing support for bare boolean values in gitconfig files
as per git-config specification. Previously these were silently
ignored.

Fixes #42

Submitting Changes

Before Submitting

  1. Ensure all tests pass:

    make test

  2. Run code quality checks:

    make codequality
make fmt

  3. Verify cross-compilation works (if changing platform-specific code):

    make crosscompile

  4. Update documentation if you changed:

    • Public API (update godoc comments)
    • User-facing behavior (update README.md, doc.go)
    • Configuration handling (update CONFIG_FORMAT.md)

Pull Request Process

  1. Push your branch to your fork
  2. Create a pull request with a clear title and description
  3. Link related issues using Closes #123 or Fixes #456
  4. Include any relevant documentation changes
  5. Be ready to respond to code review comments

What to Include in PR Description

## Description
Clear description of what changes and why.

## Type of Change
- [ ] Bug fix (non-breaking)
- [ ] New feature (non-breaking)
- [ ] Breaking change

## How to Test
Steps to verify the changes work.

## Checklist
- [ ] Tests pass locally
- [ ] Code formatted with `make fmt`
- [ ] Linting passes with `make codequality`
- [ ] Documentation updated
- [ ] No new dependencies added (or justified)

Code Review

Expect constructive feedback on:

  • Code clarity and maintainability
  • Test coverage
  • Documentation completeness
  • API design consistency
  • Performance implications

Common Patterns

Adding a New Function

  1. Implement the function
  2. Add godoc comment with:
    • What it does
    • Parameters and return values
    • Examples
    • Any error conditions
  3. Add tests covering normal and error cases
  4. Run make fmt and make codequality

Modifying Existing Functions

  1. Check if behavior change is breaking
  2. Update godoc if behavior changed
  3. Add/update tests
  4. Update related documentation

Adding Dependencies

Before adding a new dependency:

  1. Check if stdlib or existing deps can solve the problem
  2. Verify license compatibility (must be MIT or compatible)
  3. Ensure it's pure Go (no CGo)
  4. Document why it's needed in DEPENDENCIES.md
  5. Open an issue to discuss before implementing

Getting Help

  • Questions: Open a discussion or issue
  • Bug reports: Include reproduction steps, environment, Go version
  • Feature requests: Describe the use case and motivation
  • Design discussions: Open an issue to discuss before implementing

Additional Resources

License

By contributing, you agree that your contributions will be licensed under the MIT License, consistent with the project's license.

Recognition

Contributors are valued and important to this project. Your contributions help make gitconfig better for everyone.

Thank you for contributing! 🎉