Skip to content

Latest commit

 

History

History
364 lines (256 loc) · 8.39 KB

CONTRIBUTING.md

File metadata and controls

364 lines (256 loc) · 8.39 KB

🤝 Contributing to Universal Logger

First off, thank you for considering contributing to Universal Logger! It's people like you that make this project better for everyone.

📋 Table of Contents

📜 Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

🚀 How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates.

When reporting a bug, include:

  • Clear and descriptive title
  • Steps to reproduce the issue
  • Expected behavior vs actual behavior
  • Your environment (OS, Node.js version, database version)
  • Code samples or error messages

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues.

When suggesting an enhancement, include:

  • Clear and descriptive title
  • Detailed description of the proposed functionality
  • Use cases and examples
  • Why this enhancement would be useful

Your First Code Contribution

Unsure where to begin? Look for issues labeled:

  • good first issue - Simple issues perfect for beginners
  • help wanted - Issues where we need help
  • documentation - Improvements to documentation

🛠️ Development Setup

Prerequisites

  • Node.js 18+
  • npm or yarn or pnpm
  • Git

Initial Setup

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/YOUR_USERNAME/universal-logger.git
cd universal-logger

# Add upstream remote
git remote add upstream https://github.com/Jordane9999/universal-logger.git

# Install dependencies
npm install

# Build the project
npm run build

Project Structure

universal-logger/
├── src/                    # Source TypeScript files
│   ├── core/              # Core logger implementation
│   ├── adapters/          # Database adapters
│   └── types/             # TypeScript type definitions
├── dist/                  # Compiled JavaScript (generated, not committed)
├── examples/              # Usage examples
└── tests/                 # Test files (to be added)

Important: Never commit the dist/ folder - it's generated by npm run build

Available Scripts

npm run build      # Compile TypeScript to JavaScript
npm run dev        # Watch mode for development
npm test           # Run tests (when implemented)

🔄 Pull Request Process

Before Submitting

  1. Create a new branch from main:

    git checkout main
git pull upstream main
git checkout -b feature/your-feature-name

  2. Make your changes following our coding standards

  3. Test your changes:

    npm run build    # Ensure it compiles
npm test         # Run tests (when available)

  4. Update documentation if needed (README.md, JSDoc comments)

  5. Commit your changes following our commit message conventions

Submitting the PR

  1. Push to your fork:

    git push origin feature/your-feature-name

  2. Open a Pull Request on GitHub

  3. Fill out the PR template completely

  4. Wait for review - A maintainer will review your PR

PR Requirements

  • ✅ All tests pass
  • ✅ Code follows style guidelines
  • ✅ Documentation is updated
  • ✅ Commit messages follow conventions
  • ✅ No merge conflicts
  • ✅ Branch is up-to-date with main

Review Process

  1. At least one maintainer must approve
  2. All CI checks must pass
  3. No unresolved conversations
  4. Branch must be up-to-date with main

Note: The main branch is protected. You cannot push directly to it.

📝 Coding Standards

TypeScript Style

// ✅ Good
export class MongoDBAdapter implements LogAdapter {
  private client: MongoClient | null = null;

  async connect(): Promise<void> {
    // Implementation
  }
}

// ❌ Bad - Missing types
export class MongoDBAdapter {
  private client;

  async connect() {
    // Implementation
  }
}

Naming Conventions

  • Classes: PascalCase (MongoDBAdapter, UniversalLogger)
  • Functions: camelCase (createLogger, sanitizeContext)
  • Constants: UPPER_SNAKE_CASE (DEFAULT_SENSITIVE_PATTERNS)
  • Interfaces: PascalCase with 'I' prefix optional (LogAdapter, LoggerConfig)
  • Files: kebab-case for general files, PascalCase for classes (logger.ts, mongodb.ts)

Code Organization

/**
 * Brief description of the function/class
 *
 * @param config - Configuration object
 * @returns Logger instance
 * @example
 * ```typescript
 * const logger = createLogger({ adapter, service: 'api' });
 * ```
 */
export function createLogger(config: LoggerConfig): UniversalLogger {
  return new UniversalLogger(config);
}

Import Order

// 1. Node.js built-in modules
import { randomUUID } from "crypto";

// 2. External dependencies
import { MongoClient } from "mongodb";

// 3. Internal modules
import { LogAdapter, LogEntry } from "../types/index.js";

💬 Commit Messages

We follow the Conventional Commits specification.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • style: Code style changes (formatting, semicolons, etc.)
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Performance improvement
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples

# Good examples
feat(mongodb): add TTL index support
fix(logger): sanitize nested objects correctly
docs(readme): update installation instructions
refactor(adapters): simplify connection handling

# Bad examples
update stuff
fixed bug
WIP
asdfasdf

Detailed Example

feat(postgresql): add connection pooling

Implement connection pooling for PostgreSQL adapter to improve
performance and resource management.

- Add poolSize option to PostgreSQLAdapterConfig
- Reuse connections instead of creating new ones
- Add connection cleanup on close()

Closes #123

🧪 Testing

Writing Tests

// tests/logger.test.ts
import { describe, it, expect } from "vitest";
import { createLogger } from "../src/index.js";

describe("UniversalLogger", () => {
  it("should sanitize passwords", () => {
    // Test implementation
  });
});

Running Tests

npm test              # Run all tests
npm test -- --watch   # Watch mode
npm test -- --coverage # With coverage

Test Requirements

  • All new features must include tests
  • Bug fixes should include regression tests
  • Aim for >80% code coverage

🔧 Adding a New Adapter

If you want to add support for a new database:

  1. Create adapter file: src/adapters/your-db.ts

  2. Implement LogAdapter interface:

    export class YourDBAdapter implements LogAdapter {
  async connect(): Promise<void> {}
  async write(entry: LogEntry): Promise<void> {}
  async query(filter: LogFilter): Promise<LogEntry[]> {}
  async close(): Promise<void> {}
}

  3. Export from src/index.ts:

    export { createYourDBAdapter, YourDBAdapter } from "./adapters/your-db.js";
export type { YourDBAdapterConfig } from "./adapters/your-db.js";

  4. Add example: examples/your-db-example.js

  5. Update README.md with installation and usage instructions

  6. Add to package.json peerDependencies

📚 Documentation Guidelines

  • Use clear, concise language
  • Include code examples
  • Keep examples up-to-date with API changes
  • Add JSDoc comments to all public APIs
  • Update README.md for user-facing changes
  • Update CHANGELOG.md (we maintain it)

❓ Questions?

🎉 Recognition

Contributors will be recognized in:

  • README.md Contributors section
  • GitHub Contributors page
  • Release notes (for significant contributions)

Thank you for contributing! 🙏

Happy Contributing! 🚀