# Contributing to zapwall4Science

Thank you for your interest in contributing to zapwall4Science! This document provides guidelines and instructions for contributing to the project.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Coding Guidelines](#coding-guidelines)
- [Workflow](#workflow)
- [Commit Guidelines](#commit-guidelines)
- [Pull Request Process](#pull-request-process)
- [Documentation](#documentation)
- [What Not to Do](#what-not-to-do)

## Code of Conduct

By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for all contributors.

## Getting Started

1. **Fork the repository** on Gitea
2. **Clone your fork** locally:
   ```bash
   git clone https://git.4nkweb.com/your-username/story-research-zapwall.git
   cd story-research-zapwall
   ```
3. **Add the upstream remote**:
   ```bash
   git remote add upstream https://git.4nkweb.com/4nk/story-research-zapwall.git
   ```

## Development Setup

### Prerequisites

- **Node.js**: 18 or higher
- **npm**: Latest version
- **Alby browser extension**: For testing Nostr authentication and Lightning payments

### Installation

1. Install dependencies:
   ```bash
   npm install
   ```

2. Run linting:
   ```bash
   npm run lint
   ```

3. Run type checking:
   ```bash
   npm run type-check
   ```

4. Start the development server:
   ```bash
   npm run dev
   ```

5. Open [http://localhost:3000](http://localhost:3000) in your browser

## Coding Guidelines

### Core Principles

- **No fallbacks or silent failures**: All errors must be explicitly handled and logged
- **No analytics**: Analytics are not allowed in this project
- **No tests unless explicitly requested**: Do not add ad-hoc tests
- **Strict TypeScript**: Respect lint, type-check, accessibility, and `exactOptionalPropertyTypes`
- **No shortcuts**: No `ts-ignore`, no untyped `any`, no `console.log` if a logger exists

### Code Quality

- **Split large components/functions**: Stay within lint limits (max-lines, max-lines-per-function)
- **Prefer typed helpers/hooks**: Avoid duplication, reuse existing utilities
- **Error handling**: Errors must surface with clear messages; do not swallow exceptions
- **Storage**: Use IndexedDB encrypted (AES-GCM) via `lib/storage/cryptoHelpers.ts`
- **Nostr**: Use `lib/articleMutations.ts` and `lib/nostr*.ts` helpers; no direct fallbacks

### TypeScript Standards

- Full type coverage: No `any` types without explicit justification
- No type assertions: Avoid `as` casts unless absolutely necessary
- Strict mode: All TypeScript strict checks must pass
- No `@ts-ignore` or `@ts-nocheck`: Fix type issues properly

### Accessibility

- **ARIA**: Proper ARIA labels and roles
- **Keyboard navigation**: All interactive elements must be keyboard accessible
- **Contrast**: Meet WCAG contrast requirements
- **No regressions**: Maintain or improve accessibility with each change

## Workflow

### Creating a Branch

1. **Update your fork**:
   ```bash
   git checkout main
   git pull upstream main
   ```

2. **Create a feature branch**:
   ```bash
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   ```

### Making Changes

1. Make your changes following the [coding guidelines](#coding-guidelines)
2. Test your changes locally
3. Run lint and type-check:
   ```bash
   npm run lint
   npm run type-check
   ```

### Before Submitting

- [ ] Code follows the project's coding guidelines
- [ ] Lint passes (`npm run lint`)
- [ ] Type-check passes (`npm run type-check`)
- [ ] No `console.log` statements (use logger if available)
- [ ] Errors are properly handled and logged
- [ ] Accessibility requirements are met
- [ ] Documentation is updated if needed

## Commit Guidelines

### Commit Message Format

Commits should be exhaustive and synthetic with the following structure:

```
**Motivations:**
- Reason for the change

**Root causes:**
- Underlying issue (if applicable)

**Correctifs:**
- What was fixed

**Evolutions:**
- New features or improvements

**Pages affectées:**
- Files or components modified
```

### Example

```
Fix payment modal not closing after successful payment

**Motivations:**
- Users reported payment modal staying open after successful payment

**Root causes:**
- Missing state update after payment confirmation

**Correctifs:**
- Added state reset in payment success handler
- Added cleanup in useEffect hook

**Evolutions:**
- Improved user experience with automatic modal closure

**Pages affectées:**
- components/PaymentModal.tsx
- hooks/useArticlePayment.ts
```

## Pull Request Process

1. **Update your branch**:
   ```bash
   git checkout main
   git pull upstream main
   git checkout your-branch-name
   git rebase main
   ```

2. **Push your changes**:
   ```bash
   git push origin your-branch-name
   ```

3. **Create a Pull Request** on Gitea:
   - Use a clear, descriptive title
   - Fill out the PR template completely
   - Reference any related issues
   - Add screenshots if UI changes are involved

4. **Wait for review**: Maintainers will review your PR and provide feedback

5. **Address feedback**: Make requested changes and push updates to your branch

6. **Documentation**:
   - Document fixes in `fixKnowledge/` directory
   - Document features in `features/` directory

## Documentation

### When to Document

- **Fixes**: Document in `fixKnowledge/` with problem, impacts, root cause, corrections, modifications, deployment, and analysis procedures
- **Features**: Document in `features/` with objective, impacts, modifications, deployment, and analysis procedures

### Documentation Format

Follow the existing documentation structure:
- Clear sections with headers
- Code examples where relevant
- Links to related documentation
- Author attribution (Équipe 4NK)

## What Not to Do

- ❌ **No analytics**: Do not add analytics tracking
- ❌ **No ad-hoc tests**: Do not add tests unless explicitly requested
- ❌ **No environment overrides**: Do not override environment variables
- ❌ **No silent retry/fallback**: All failures must be explicit
- ❌ **No shortcuts**: No `ts-ignore`, no `any`, no `console.log`
- ❌ **No breaking changes**: Maintain backward compatibility unless explicitly required

## Getting Help

- **Documentation**: Check the [docs/](docs/) directory
- **Issues**: Search existing issues or create a new one on [Gitea](https://git.4nkweb.com/4nk/story-research-zapwall/issues)
- **Repository**: [https://git.4nkweb.com/4nk/story-research-zapwall](https://git.4nkweb.com/4nk/story-research-zapwall)

Thank you for contributing to zapwall4Science! 🚀