# 🤝 Guía de Contribución — CyberSec Events Tracker

Gracias por tu interés en contribuir. Este documento describe el proceso y las convenciones del proyecto.

## Formas de contribuir

1. **Sugerir un evento** — Abre un [issue con el template](https://github.com/ttpsec/cybersec-events-tracker/issues/new?template=nuevo-evento.yml)
2. **Agregar una fuente** — Propón nuevas fuentes de scraping via issue
3. **Reportar bugs** — Usa el template de bug report
4. **Mejorar código** — Envía un Pull Request
5. **Mejorar documentación** — PRs de docs siempre son bienvenidos

## Requisitos para Pull Requests

### Antes de enviar

1. Fork el repositorio y crea un branch desde `main`
2. Nombra tu branch con el formato: `tipo/descripcion-corta`
   - Ejemplos: `feat/add-source-bsides`, `fix/date-parsing`, `docs/update-readme`
3. Asegúrate de que el scraper corre sin errores:
   ```bash
   pip install -r requirements.txt
   python scraper.py --generate --stats
   ```
4. No incluyas archivos generados (`README.md`, `docs/*.md`, `data/events.json`) en PRs de código — estos se regeneran automáticamente

### Checklist del PR

- [ ] El código funciona localmente sin errores
- [ ] Se siguieron las convenciones de estilo del proyecto
- [ ] No se incluyen credenciales, tokens o datos sensibles
- [ ] La descripción del PR explica el _por qué_ del cambio

## Convención de commits

Usamos [Conventional Commits](https://www.conventionalcommits.org/):

```
<tipo>(<alcance>): <descripción>

[cuerpo opcional]

[footer opcional]
```

### Tipos permitidos

| Tipo | Descripción |
| ---- | ----------- |
| `feat` | Nueva funcionalidad |
| `fix` | Corrección de bug |
| `docs` | Cambios en documentación |
| `style` | Formato, sin cambios funcionales |
| `refactor` | Refactorización sin cambio funcional |
| `test` | Agregar o corregir tests |
| `chore` | Tareas de mantenimiento |
| `security` | Parches de seguridad |

### Ejemplos

```
feat(scraper): add BSides LATAM as new source
fix(parser): handle dates with missing year field
docs(readme): update installation instructions
security(deps): bump requests to 2.32.0
```

## Estilo de código

### Python

- **Versión mínima:** Python 3.11
- **Formatter:** Seguir PEP 8
- **Naming:**
  - Funciones y variables: `snake_case`
  - Clases: `PascalCase`
  - Constantes: `UPPER_SNAKE_CASE`
- **Docstrings:** En español, formato de una línea para funciones simples
- **Imports:** Agrupados por stdlib → terceros → locales, ordenados alfabéticamente
- **Type hints:** Usar para firmas de funciones públicas

### Markdown

- Tablas alineadas
- Links relativos dentro del repo
- Emojis solo en headers de sección

## Proceso de revisión

1. Un maintainer revisará tu PR dentro de **5 días hábiles**
2. Se pueden solicitar cambios antes de aprobar
3. Los PRs requieren al menos **1 aprobación** para merge
4. Se usa **squash merge** para mantener el historial limpio

## Agregar una nueva fuente de scraping

Para agregar una fuente al array `FUENTES` en `scraper.py`:

```python
{"id": N, "nombre": "Nombre de la Fuente", "url": "https://...", "foco": "Ciberseguridad, ..."},
```

Requisitos:
- La URL debe ser pública y accesible
- El sitio debe contener eventos con fechas extraíbles
- Debe ser relevante a ciberseguridad, tecnología o innovación
- Preferencia por fuentes en español o bilingües

## Agregar eventos semilla

Para agregar un evento verificado al array `EVENTOS_SEMILLA`:

1. Verificar que el evento es real y tiene fecha confirmada
2. Incluir todos los campos obligatorios (name, date_start, country, region, categories, url)
3. Usar el formato ISO 8601 para fechas (`YYYY-MM-DD`)
4. Asignar categorías del array `CATEGORIAS`

## Código de conducta

Este proyecto sigue el [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

En resumen:
- Sé respetuoso y constructivo
- No se tolera acoso, discriminación ni lenguaje ofensivo
- Enfócate en el proyecto, no en las personas
- Reporta comportamiento inaceptable a security@ttpsec.cl

---

_Mantenido por [TTPSEC SpA](https://ttpsec.cl)_