Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
325 lines (236 loc) · 8.49 KB

CONTRIBUTING.md

File metadata and controls

325 lines (236 loc) · 8.49 KB

Contributing to aSSO

Thank you for your interest in contributing to aSSO! This document provides guidelines and standards for contributing to this project.

Table of Contents

Commit Message Guidelines

This project uses Conventional Commits for all commit messages. This leads to more readable messages that are easy to follow when looking through the project history, and enables automatic version bumping and changelog generation.

Commit Message Format

Each commit message consists of a header, an optional body, and an optional footer:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The header is mandatory and must conform to the Conventional Commits format.

Type

Must be one of the following:

  • feat: A new feature (triggers MINOR version bump)
  • fix: A bug fix (triggers PATCH version bump)
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, etc.)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to CI configuration files and scripts
  • chore: Other changes that don't modify src or test files
  • revert: Reverts a previous commit

Scope

The scope is optional and should be a noun describing a section of the codebase surrounded by parentheses:

Examples: feat(ui), fix(auth), docs(readme)

Common scopes:

  • ui - User interface / TUI changes
  • auth - Authentication/SSO related
  • aws - AWS SDK integration
  • k8s - Kubernetes integration
  • config - Configuration handling
  • cli - Command-line interface

Description

The description is a short summary of the code changes:

  • Use the imperative, present tense: "change" not "changed" nor "changes"
  • Don't capitalize the first letter
  • No period (.) at the end
  • Keep it under 72 characters

Body

The body is optional and should provide additional context about the changes:

  • Use the imperative, present tense
  • Include motivation for the change
  • Contrast this with previous behavior
  • Wrap at 100 characters

Footer

The footer is optional and should contain:

  • Breaking Changes: Must start with BREAKING CHANGE: followed by a description
  • Issue References: Closes #123, Fixes #456, Refs #789

Examples

Simple feature

feat: add SSO authentication cancellation

Allow users to cancel SSO authentication flow by pressing esc or q

Feature with scope

feat(ui): add bordered panes with focus indicators

- Add FocusedPaneBorderStyle and UnfocusedPaneBorderStyle
- Update profile list view with bordered panes
- Update company view with 3-pane bordered layout
- Active pane shows bright blue border
- Inactive panes show gray border

Bug fix

fix(ui): correct profile list scaling on small terminals

Improve viewport calculation to prevent content overflow when
terminal height is less than 30 lines.

Breaking change

feat(api)!: change profile name format

BREAKING CHANGE: Profile names now use format company-env instead of company_env.
This affects all existing profiles and requires migration.

Migration: Run `asso migrate-profiles` to update existing profiles.

Documentation

docs: update CLAUDE.md with session 4 notes

Document SSO cancellation feature and bordered panes implementation.

Refactoring

refactor(view): consolidate pane width calculations

Extract common pane width logic into helper function to reduce
duplication between profile list and company views.

Commit Message Validation

This project includes a Git hook that automatically validates commit messages. If your commit message doesn't follow the Conventional Commits format, the commit will be rejected with a helpful error message.

To test your commit message format before committing:

echo "feat: my commit message" | grep -E '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9\-]+\))?: .{1,50}'

Semantic Versioning

This project follows Semantic Versioning (SemVer):

Given a version number MAJOR.MINOR.PATCH:

  • MAJOR version increments indicate incompatible API changes
  • MINOR version increments indicate new features in a backwards-compatible manner
  • PATCH version increments indicate backwards-compatible bug fixes

How Commits Affect Versions

  • feat: commits → MINOR version bump
  • fix: commits → PATCH version bump
  • BREAKING CHANGE: in footer → MAJOR version bump
  • Other commit types → No version bump (included in next release)

Version Bumping

Versions are managed manually based on the Conventional Commits since release:

# Review commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Create new version tag
git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

Development Workflow

Setting Up Development Environment

  1. Clone the repository

    git clone <repository-url>
cd aSSO

  2. Install dependencies

    go mod download

  3. Install development tools (optional)

    go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

  4. Verify hooks are executable

    chmod +x .git/hooks/commit-msg

Making Changes

  1. Create a feature branch

    git checkout -b feat/my-new-feature
# or
git checkout -b fix/issue-123

  2. Make your changes

    • Write code
    • Add tests
    • Update documentation

  3. Test your changes

    go test -short ./...
go build -o asso
./asso  # Manual testing

  4. Commit your changes

    git add .
git commit -m "feat: add my new feature"

    The commit-msg hook will validate your message format.

  5. Push and create PR (if applicable)

    git push origin feat/my-new-feature

Commit Frequency

  • Commit early and often: Make small, logical commits
  • Each commit should be atomic: One logical change per commit
  • Keep commits focused: Don't mix multiple unrelated changes
  • Build should pass after each commit: Every commit should leave the code in a working state

Examples of good commit granularity:

git commit -m "feat(ui): add border style definitions"
git commit -m "feat(ui): apply borders to profile list view"
git commit -m "feat(ui): apply borders to company view"
git commit -m "test(ui): add border focus indicator tests"
git commit -m "docs: document bordered pane feature"

Code Style

Go Code Guidelines

  • Follow standard Go conventions
  • Use gofmt for formatting (automatically applied by most editors)
  • Use meaningful variable and function names
  • Add comments for exported functions and complex logic
  • Keep functions small and focused

TUI/UI Guidelines

  • Use lipgloss for all styling
  • Define reusable styles in styles.go
  • Keep view rendering logic separate from state management
  • Test views with different terminal sizes

Testing

Running Tests

# Run all tests
go test ./...

# Run tests without integration tests
go test -short ./...

# Run tests with coverage
go test -short -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# Run specific test
go test -run TestBorderFocus ./internal/ui/

Writing Tests

  • Write tests for new features
  • Write tests for bug fixes
  • Use table-driven tests when appropriate
  • Mock external dependencies (AWS SDK, kubectl, etc.)
  • Use -short flag for unit tests

Example test structure:

func TestMyFeature(t *testing.T) {
    tests := []struct {
        name string
        input string
        want string
    }{
        {"case 1", "input1", "output1"},
        {"case 2", "input2", "output2"},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := MyFeature(tt.input)
            if got != tt.want {
                t.Errorf("MyFeature() = %v, want %v", got, tt.want)
            }
        })
    }
}

Questions?

If you have questions about contributing, feel free to open an issue for discussion.

Thank you for contributing to aSSO!