@gftdcojp/weblate-nextjs-sdk/CONTRIBUTING.md

A Next.js SDK for integrating with Weblate translation management system

# Contributing to Weblate Next.js SDK

First off, thank you for considering contributing to the Weblate Next.js SDK! 🎉

## Code of Conduct

This project and everyone participating in it is governed by our commitment to providing a welcoming and inclusive environment for all contributors.

## How Can I Contribute?

### Reporting Bugs 🐛

Before creating bug reports, please check the existing issues to avoid duplicates. When creating a bug report, please include:

- **Use a clear and descriptive title**
- **Describe the exact steps to reproduce the problem**
- **Provide specific examples to demonstrate the steps**
- **Describe the behavior you observed after following the steps**
- **Explain which behavior you expected to see instead**
- **Include screenshots if possible**

### Suggesting Enhancements 💡

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

- **Use a clear and descriptive title**
- **Provide a step-by-step description of the suggested enhancement**
- **Provide specific examples to demonstrate the steps**
- **Describe the current behavior and explain which behavior you expected to see instead**
- **Explain why this enhancement would be useful**

### Your First Code Contribution 🚀

Unsure where to begin contributing? You can start by looking through these `beginner` and `help-wanted` issues:

- **Beginner issues** - issues which should only require a few lines of code
- **Help wanted issues** - issues which should be a bit more involved

## Development Setup

### Prerequisites

- Node.js 18.x or later
- pnpm (recommended package manager)

### Setting up the development environment

1. Fork the repository on GitHub
2. Clone your fork locally:
   ```bash
   git clone https://github.com/your-username/weblate-nextjs-sdk.git
   cd weblate-nextjs-sdk
   ```

3. Install dependencies:
   ```bash
   pnpm install
   ```

4. Create a feature branch:
   ```bash
   git checkout -b feature/your-feature-name
   ```

### Development Commands

```bash
# Run type checking
pnpm type-check

# Run linting
pnpm lint

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Build the package
pnpm build

# Run example application
pnpm example:dev
```

### Project Structure

```
@gftdcojp/weblate-nextjs-sdk/
├── src/
│   ├── client/          # Weblate API client
│   ├── hooks/           # React hooks
│   ├── context/         # React context providers
│   ├── types/           # TypeScript type definitions
│   └── __tests__/       # Test files
├── example/             # Example Next.js application
├── dist/                # Built files (auto-generated)
└── .github/             # GitHub Actions workflows
```

## Pull Request Process

1. **Fork the repository** and create your branch from `main`
2. **Add tests** for any new functionality
3. **Ensure the test suite passes** (`pnpm test`)
4. **Make sure your code lints** (`pnpm lint`)
5. **Ensure type checking passes** (`pnpm type-check`)
6. **Update documentation** if needed
7. **Write a good commit message** (see below)

### Commit Message Guidelines

We follow the [Conventional Commits](https://conventionalcommits.org/) specification:

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

**Types:**
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `style`: Changes that do not affect the meaning of the code
- `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
- `chore`: Changes to the build process or auxiliary tools

**Examples:**
```
feat(hooks): add useComponentLanguages hook
fix(client): handle API timeout errors properly
docs(readme): update installation instructions
test(client): add tests for error handling
```

## Coding Style

- **Use TypeScript** for all new code
- **Follow the existing code style** (enforced by ESLint)
- **Write meaningful variable and function names**
- **Add JSDoc comments** for public APIs
- **Keep functions small and focused**
- **Use async/await** instead of callbacks

### Type Safety

- **Always type your functions** with proper input and output types
- **Use interfaces** for object types
- **Avoid `any` type** unless absolutely necessary
- **Export types** that might be useful for consumers

## Testing

- **Write tests** for all new functionality
- **Test both success and error cases**
- **Use descriptive test names**
- **Mock external dependencies** (like API calls)
- **Aim for good test coverage**

### Test Structure

```typescript
describe('ComponentName', () => {
  describe('method name', () => {
    it('should do something when condition is met', () => {
      // Test implementation
    });
  });
});
```

## Documentation

- **Update README.md** if adding new features
- **Add JSDoc comments** for public APIs
- **Include usage examples** in code comments
- **Update TypeScript definitions** if needed

## Releasing

Releases are automated via GitHub Actions:

1. **Create a PR** with your changes
2. **Merge the PR** into `main`
3. **Create a new version tag**: `git tag v1.x.x`
4. **Push the tag**: `git push origin v1.x.x`
5. **GitHub Actions** will automatically publish to npm

## Getting Help

- **GitHub Issues** - for bug reports and feature requests
- **GitHub Discussions** - for questions and general discussion
- **Documentation** - check the README and code comments

## Recognition

Contributors will be recognized in:
- The project's README
- Release notes
- GitHub contributors list

Thank you for contributing! 🙏