pagination-front-end/CONTRIBUTING.md

pagination-front-end é uma biblioteca voltada para realização de paginação no front end( pagination-front-end is a front-end paging library)

# Guia de Contribuição (Contributing Guide)

Obrigado por considerar contribuir com o **pagination-front-end**!  
Thank you for considering contributing to **pagination-front-end**!

Este documento descreve como configurar o ambiente, desenvolver alterações e enviar contribuições.  
This document describes how to set up the environment, develop changes, and submit contributions.

## Índice (Table of contents)

- [Código de conduta (Code of conduct)](#código-de-conduta-code-of-conduct)
- [Como contribuir (How to contribute)](#como-contribuir-how-to-contribute)
- [Configuração do ambiente (Environment setup)](#configuração-do-ambiente-environment-setup)
- [Desenvolvimento (Development)](#desenvolvimento-development)
- [Testes (Tests)](#testes-tests)
- [Padrões de código (Code standards)](#padrões-de-código-code-standards)
- [Pull requests](#pull-requests)
- [Reportar problemas (Reporting issues)](#reportar-problemas-reporting-issues)

## Código de conduta (Code of conduct)

Seja respeitoso e construtivo. Contribuições que incluam assédio, discriminação ou comportamento ofensivo não serão aceitas.

Be respectful and constructive. Contributions involving harassment, discrimination, or offensive behavior will not be accepted.

## Como contribuir (How to contribute)

Você pode contribuir de várias formas:

You can contribute in several ways:

- Corrigir bugs
- Adicionar novos recursos
- Melhorar documentação
- Aumentar cobertura de testes
- Sugerir melhorias via issues

- Fix bugs
- Add new features
- Improve documentation
- Increase test coverage
- Suggest improvements via issues

Antes de iniciar uma alteração grande, abra uma issue para discutir a proposta e evitar trabalho duplicado.

Before starting a large change, open an issue to discuss the proposal and avoid duplicated work.

## Configuração do ambiente (Environment setup)

### Pré-requisitos (Prerequisites)

- [Node.js](https://nodejs.org/) (versão LTS recomendada / LTS version recommended)
- npm ou yarn

### Instalação (Installation)

```bash
# Clone o repositório (Clone the repository)
git clone https://github.com/jhony2488/pagination-frontend.git
cd pagination-frontend

# Instale as dependências (Install dependencies)
npm install
```

## Desenvolvimento (Development)

A estrutura principal do projeto:

Main project structure:

```text
src/           # Código-fonte TypeScript (TypeScript source code)
__tests__/     # Testes unitários (Unit tests)
dist/          # Build gerada pelo Babel (Babel build output)
```

### Scripts disponíveis (Available scripts)

```bash
# Executar testes (Run tests)
npm test

# Gerar build de publicação (Generate publish build)
npm run build
```

> **Windows:** o script `npm test` usa `NODE_ENV=test`, sintaxe comum em Unix. No PowerShell, use:
>
> ```powershell
> $env:NODE_ENV='test'; npx jest --detectOpenHandles
> ```

## Testes (Tests)

Toda alteração deve manter os testes passando.

All changes must keep tests passing.

- Novos recursos devem incluir testes em `__tests__/unit/`
- Correções de bugs devem incluir testes que reproduzam o problema
- Execute `npm test` antes de abrir um pull request

- New features should include tests in `__tests__/unit/`
- Bug fixes should include tests that reproduce the issue
- Run `npm test` before opening a pull request

Os mocks de teste ficam em `__tests__/mock/`.

Test mocks are located in `__tests__/mock/`.

## Padrões de código (Code standards)

Este projeto usa:

This project uses:

- **TypeScript**
- **ESLint** (configuração Airbnb + TypeScript)
- **Prettier** (sem ponto e vírgula, aspas simples / no semicolons, single quotes)

Convenções importantes:

Important conventions:

- Mantenha a API pública retrocompatível, salvo acordo em issue
- Prefira funções pequenas e testáveis em `src/utils/`
- Comentários bilíngues (PT/EN) são bem-vindos quando explicarem regras de negócio
- Evite alterações não relacionadas no mesmo pull request

- Keep the public API backward compatible unless agreed in an issue
- Prefer small, testable functions in `src/utils/`
- Bilingual comments (PT/EN) are welcome when explaining business rules
- Avoid unrelated changes in the same pull request

## Pull requests

1. Faça fork do repositório
2. Crie uma branch descritiva (`fix/pagination-edge-case`, `feat/new-option`)
3. Implemente a alteração com testes
4. Confirme que `npm test` e `npm run build` passam
5. Abra o pull request descrevendo o problema e a solução

1. Fork the repository
2. Create a descriptive branch (`fix/pagination-edge-case`, `feat/new-option`)
3. Implement the change with tests
4. Confirm `npm test` and `npm run build` pass
5. Open a pull request describing the problem and solution

### Checklist do PR (PR checklist)

- [ ] Testes adicionados ou atualizados / Tests added or updated
- [ ] `npm test` passou / `npm test` passed
- [ ] `npm run build` passou / `npm run build` passed
- [ ] README atualizado, se necessário / README updated, if needed
- [ ] Alteração focada e com escopo claro / Focused change with clear scope

## Reportar problemas (Reporting issues)

Ao abrir uma issue, inclua:

When opening an issue, include:

- Descrição clara do problema ou sugestão
- Passos para reproduzir (se for bug)
- Comportamento esperado vs. atual
- Versão do Node.js e do pacote

- Clear description of the problem or suggestion
- Steps to reproduce (for bugs)
- Expected vs. actual behavior
- Node.js and package version

---

Contribuições são bem-vindas. Obrigado por ajudar a melhorar esta biblioteca!

Contributions are welcome. Thank you for helping improve this library!